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1. THE TELIX SALT LANGUAGE 


Telix has a built-in programming language called SALT (Script Applica- 
tion Language for Telix). SALT will allow you to perform almost any 
communications related applications with Telix. SALT looks similar to 
the C language, however if you have used almost any programming lan- 
guage (such as Pascal, BASIC, etc.), you should feel quite at home 
with SALT. While SALT was designed to be easy to learn, it is like 
most programming languages quite complete, so it is recommended that 
you read this chapter thoroughly and study the examples provided, as 
well as the sample SALT scripts included with Telix. 


1.1 What Can be Accomplished With SALT? 


9999999999999 999999999999 9H9 9 
9999999999 999999999999 99999999 


Like a program in any programming language, a SALT program (also 
called a 'script') is typically used to perform a needed task or func- 
tion. The task can range from the very simple to the very complicated. 
For example, a SALT script can be linked to a dialing directory entry, 
so that when you have established a connection to that service, it au- 
tomatically sends your i.d. and password to the remote service. A much 
more complicated SALT script is used as the basis for the Host Mode 
included with Telix. 


1.2 About This Manual 


99999 99999999999 999999999999 999999999999 
9999999999999 999999999999 99999 


This manual is basically a reference to the SALT programming language. 
It is by no means a tutorial on programming in general. It is assumed 
that the reader of this manual is at least familiar with general pro- 
gramming concepts. 


1.3 Notation 


9999999999999 999999999999 999999999999 999 
9999999999999 999999999999 99999 


Throughout this manual, certain words in examples and in the text will 
be surrounded by angle brackets and italicized, for example, 
<expression>. These words are not to be taken as literal text. they 
stand for something else, such as a word, a group of words, or even 
several lines of text. What these italicized words stand for will be 
explained as they come up. 


1.4 Creating SALT Programs 


99999 99999999999 999999999999 999999999999 
9999999999 999999999999 99999999 


A SALT script is basically a sequence of instructions for Telix to 
follow, using a specific syntax. You may use any text editor to pro- 
duce this script file, as long as its output is normal ASCII text 
(this means that if you use your word processor, you must usually ex- 
plicitly tell it to write out the file using ASCII format and to not 
embed any special codes in the file). You may give any name you wish 
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to a SALT source file, although we recommend that you always use the 
extension .SLT for clarity. 


Once you have written your script file and saved it to disk, it must 
be compiled. The program CS.EXE included with Telix reads your 
'source' script file, and compiles it to a form which Telix can under- 
stand. The compiled script can then be loaded more quickly by Telix, 
and is also usually smaller. 


To compile a script source file, type 
cs <pathname> 


while at the DOS prompt and then press Enter (or Carriage Return). The 
CS.EXE program must be in the current directory or on the DOS PATH. 
<pathname> is the name of the file to compile, and may include the 
drive and directory as well as the filename. The output file is writ- 
ten to the same name except that the extension .SLC is used. 


when the script compiler finds an error in your source file, it will 
abort the compile process and give you the line number on which the 
error occurred, as well as the type of error. The error should then be 
fixed and the source re-compiled. This is repeated until the compiler 
detects no more errors in your source file. 


The compiled script can then be run in Telix using several methods. It 
may be run using the 'Run script' command, as a command-line option 
when running Telix from DOS, as a linked script to a dialing directory 
entry, or from another script. The first three methods are described 
in the Telix manual, while the last is described later in this manual. 
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2. SYNTAX 


Case is not important in command, function, and variable names. The 
only time case matters is inside a string constant (e.g., "Hello" is 
not the same string as "hello"). Whitespace (such as the space, the 
tab, the Carriage Return, or the Line Feed character) is not impor- 
tant. The script compiler does not care where you place items, so that 
you may arrange the program as you see fit. For example, 


if (value == 1) 
prints("value is equal to 1!"); 
else 
prints("values is not equal to 1."); 


is equivalent to 


if (value == 1) prints("value is equal to 1!"); 
else prints("value is not equal to 1"); 


or even to 


if(value==1)prints("value is equal to 1!");else prints("value is 
not equal to 1."); 


The only time whitespace matters is when it would split up key-words 
or function name, or in a string. For example, the key-word 'while' 
must not be split up if it is to be recognized. The same applies to 
other key-words or function names. As well, there must be space be- 
tween the letters of a command and other letters. For example, 'while' 
is not the same as 'whileabc'. In the interest of clarity, it is rec- 
ommended that you try to make your code easy to understand, by indent- 
ing where appropriate, and by using space effectively. There is no 
reason, for example, to put more than one statement on a line, even if 
it is perfectly legal. A good example of program style can be found by 
looking at the sample scripts included with Telix. 


A string constant is a sequence of ASCII characters enclosed in 
quotes, for example, "Hello", "Good-bye", or "Telix". It is often nec- 
essary for a string constant to include special characters that can 
not easily be typed from the keyboard, or can not be easily displayed. 
This is done with something called the escape character, which is the 
caret ('A') symbol. When the SALT compiler is reading a string con- 
stant and comes to the 'A' symbol, it replaces it with a certain ASCII 
code based on the character following the “. Translations are as fol- 
lows: 


AC 'c' is a letter. The Control representation of whatever 
letter 'c' is, is inserted into the text. Therefore AM 
represents Ctrl-M, 4j represents Ctrl-J, etc. Whether 
the letter 'c' is upper or lower case is not signifi- 
cant. Note that what is really happening here is that 
64 is being subtracted from the value of 'c', so for 
example, the Escape character can be represented as /[. 

AN An actual caret ('4') symbol is placed into the text. 


Telix v3.22 - SALT Programming Syntax 4 


a" An actual double quote symbol ('"') is placed into the 
text. If a string must contain a double quote symbol, 
this is how it has to be done. If the plain '"' symbol 


were to be used, the compiler would think that the 
string was terminated at that point. For example, the 


string "He said, *"HelloX"." is translated to 'He said, 
"Hello".'. 

N! An actual single quote symbol (''') is placed into the 
text. 

Annn 'nnn' is up to 3 digits representing the ASCII value of 


the character which should be placed into the text. A 
maximum of three digits is read, or up to the first 
non-digit character. For example, the compiler would 
read in the string "SA65LT" and output the string 
"SALT", since 65 is the ASCII value of 'A'. Note that 
if nnn is less than 3 digits you may have to pad it 
with one or two leading zeros if there are digits imme- 
diately following it in the string, so that the wrong 
value is not read in. For example the string "479 Park 
Avenue" would translate to "O Park Avenue" since 79 is 
the ASCII value of '0'. If you actually wanted Ctrl-G 
(ASCII code 7) followed by "9 Park Avenue", you would 
use the string "40079 Park Avenue". 


An integer constant is a sequence of digits representing an integer 
value in the range -2147483648 to 2147483647. An integer constant must 
start with a digit from 0 to 9 or the negative sign (-) followed by a 
digit. The following are all valid integer constants: 


10 
-400067 
999 


An integer constant may also be entered in hexadecimal form (base 16, 
where each digit may be from '0' to '9' or 'a' to 'f', to represent 16 
values). Hex values must be preceded by '0x' for the compiler to in- 
terpret them as such, and case is not important. The following are all 
valid integer constants enter in hexadecimal form: 


Oxf foo 
0xa2 

Ox7D 
Ox1AbCdEf 


2.1 Comments 


9999999999999 999999999999 999999999999 9H9 9 
9999999999999 999999999999 99999 


A comment in a source file is text that does not affect what the pro- 
gram does, and is meant purely for explaining or describing something. 
In a SALT source file, whenever the symbol // is encountered on a 
line, all the characters from that point on until the end of the line 
are considered to be a comment and are ignored. For example: 


prints("Hello"); // This line will print "Hello" 
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3. PROGRAM STRUCTURE 

A SALT script has the following format: 
<global_variable_definition> 
<global_variable_definition> 
<function_definition> 
<global_variable_definition> 
<global_variable_definition> 


<Function_definitions> 


and so on. Basically a script file consists of definition of global 
variables (variables which are available to any part of the script 
file after which they are defined, and function definitions (functions 
are lines of code clustered together in a group, so that they can be 
called by a name). A script file does not have to have any global 
variables or functions, but to run it must at least have one function 
called 'main'. The following, for example, is a complete script file: 


main() 


L 
prints ("hello"); 


} 


When compiled and run, this script would print the string "hello" to 
the screen. 


3.1 Variables 


999 9999999999999 999999999999 999999999 d Aa A 
9999999999999 999999 99999999999 


A variable is a location in memory where something is stored. The con- 
tents of a variable can be changed by program code (hence the name). 
In SALT, there are two types of variables, integer variables, and 
string variables. The former holds an integer value (e.g., 485624, or 
-627), while the latter holds a text string (e.g. "Telix", or 
"SCRIPT"). Depending on where it is defined, a variable is either 
global or local. If a variable is global, it means that it can be used 
by any part of the script after the point where it is defined. If a 
variable is local, it means that it can only be used by the part of 
the script to which it is 'local', for example, the function inside 
which it is defined. A variable name can be up to 31 digits long, and 
may include the letters 'A' to 'Z' or 'a' to 'z', the digits '0' to 
'9', or the underscore character (_). The name may not start with a 
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digit. For example, 'his_name2' and '_his_name2' are legal as variable 
names, while '2his_name' is not. 


An integer variable is defined in the form 
int <varname>; 


where <varname> is the name to be given to the variable. An alternate 
definition is 

int <varnamei>, <varname2>, ..., <varnameN>; 
which allows you to define more than one integer variable in one 


statement. An original value can be assigned to the integer variable 
by using the form 


int <varname> = <int_const>; 
where <int_const> is an integer constant. Similarly, an original value 
can be assigned in the multiple definition above by placing the as- 
signment before the comma. Some examples are: 

int maximum; 

int start = 0; 

int level, i, count = 20, loop; 
A string variable is defined in the form 

str <varname>[<max>]; 
where <varname> is the name to be given to the variable. <max> is the 
maximum number of characters that the string can hold, and must be in 
the range of © to 32767. An alternate definition is 

str <varname>[<max>], <varname2>[<max>], ..., <varnameN>[<max>]; 
which allows you to define more than one string variable in a state- 
ment. An original value can be assigned to the string variable by us- 
ing the form 

str <varname>[<max>] = <str_const>; 
where <str_const> is a string constant. Similarly, an original value 
can be assigned in the multiple definition above by placing the as- 


signment before the comma. Some examples are: 


str password[80]; 
str password[40] = "mypass", name[30]; 


The string length field may be left empty if an original value is 
specified, in which case the length of the string variable is assumed 
to be that of the assigned text, e.g. 


str name[] = "John"; 


If a variable is outside of a function, it is global. If it is defined 
inside a function, it is local to that function and will only be rec- 
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ognized there. If a variable defined inside a function uses the same 
name as a global variable, any reference to that name while in the 
function will access the local variable. After the function has com- 
pleted, the local variable is removed and a reference to that name 
will access the global variable. 


3.2 Expressions and Operators 


9999999999999 999999999999 999999999999 999 
999 999999999999 H 99999999999 OO9 


An expression is a mixture of symbols which resolves to a value when 
evaluated. In other words, an expression is basically a formula. An 
expression can consist of constants, variables, function calls, and 
operators. An expression can be very simple, or very complicated. For 
example, some expressions are: 


10 +3 -5 

9 * 7 / 63 - 30 

result = 10 * max(a, b) 
month >= 10 

200 

command == "bye" 
prints("Hello") 


In an expression, the data being acted upon are constants, variables, 
and functions calls, while the operators (+, *, etc.) are the symbols 
that do things with the data. There are many different operators, of 
which there are two basic types. Binary operators (such as +, *, /) 
perform a calculation on the expression on either side of them. Unary 
operators appear before a single expression and work on that. The fol- 
lowing table lists the operators available in SALT: 


Symbol (Un/Bin)ary What it is/does 

- unary Arithmetic negation 

! unary Logical NOT 
not unary Logical NOT (alternate) 
++ unary Increment 

-- unary Decrement 

ig binary Multiplication 

/ binary Division 

% binary Remainder (Mod) 

+ binary Addition 

- binary Subtraction 

< binary Less than 

> binary Grater than 

<= binary Less than or equal to 
>= binary Greater than or equal to 
== binary Equality 

[= binary Inequality 

& binary Bitwise AND 

| binary Bitwise OR 

N binary Bitwise Exclusive OR 
&& binary Logical AND 
and binary Logical AND (alternate) 
| | binary Logical OR 

or binary Logical OR (alternate) 


= binary Assignment 
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Note that the hyphen symbol can be either an arithmetic negation or a 
subtraction depending on its use. Note that '!' is equivalent to 
'not', '&&' is equivalent to 'and', and '||' is equivalent to 'or'. 
The first form is preferred as you do not have to leave whitespace 
around it for the compiler to recognize it, but beginners may have an 
easier time remembering the second form. Also, do not confuse the '=' 
(assignment operator) with the '==' (equality operator). The former is 
used to assign a value to a variable, while the latter is used to com- 
pare two values. Assuming you have the two expressions, <expri> and 
<expr2>, <expri> = <expr2> would assign one to the other, while 


<expri> == <expr2> would test the two to see if they are equal. For 
example 
num = 10 


would assign the value 10 to the variable called 'num', while 
num == 10 


would resolve to a value of non-zero (TRUE) if num was equal to 10, 
and © (FALSE) if num was not equal to 10. There is also a difference 
between the Logical operators and the Bitwise operators. The Logical 
operators (such as and, && or, ||, etc), work with TRUE or FALSE val- 
ues and result in a TRUE or FALSE value, while the Bitwise operators 
(€, |, ^) work with the actual bits of the data they are handling. The 
Bitwise operators almost never have to be used in a Telix script, un- 
less it is needed to get at the actual bits in a data byte. 


Every operator resolves to a value, which is the result of the opera- 
tion performed (e.g, 10 * 7 would resolve to 70). The conditional or 

equality operators such as ==, >, <=, etc., resolve to a 0 (FALSE)) 

or non-zero (TRUE) value based on the results of the expression. Even 
the assignment operator = resolves to a value. The result of the ex- 

pression 


num = 10 
would be 10. 


All the operators have something called precedence, which is their im- 
portance, and determines the order in which they are evaluated. For 
example, 7 + 3 * 9 is equal to 34, because 3 * 9 is evaluated first, 
and then added to 7 (* has a higher precedence than +). All the opera- 
tors are listed below in order of decreasing precedence. All the oper- 
ators on the same line have the same precedence, and are resolved in 
the order that they are encountered. 


99 
$9 9 


Telix v3.22 - SALT Programming Program Structure 9 


If a certain evaluation order is required that does not follow these 
rules of precedence, parentheses may be used. Thus, 99 + 1 * 10 equals 
109, while (99 + 1) * 10 equals 1000. 


If you are writing an expression of any sort, and are not sure of the 
exact precedence of the operators you are using, use parentheses! 


3.3 Functions 


Y990099909909099090990909909099090909090909099009000900000 
Y990999099090990909909099090909009000 


A function is a way of grouping together some lines of code. A Telix 
script consists of one or more functions. There are quite a few advan- 
tages to having functions: 


One function can be called from another, to do a certain task. 
The calling function does not have to know anything about the 
called function other than what it does. This allows a script to 
be split up into modular units, and makes code writing and debug- 
ging easier. 

As mentioned above, what a function does it private. This means 
that data variables defined in a function are local to that func- 
tion, and therefore you do not have to worry about another part 
of the script unintentionally modifying them. 


A library of functions can thus be built. Later, you do not have 
to re-write old code. 


Functions are defined in the following format: 


<funcname>(<arg1>, <arg2>, ..., <argN>) 


<variable_def> 
<variable_def> 
<statement> 


<statement> 


} 
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<funcname> is the name of the function. It follows the same rules of 
other identifiers in SALT. There can only be one function that uses a 
given name, however. 


<argi> through <argN> are the declarations of the arguments 
(parameters) that have been passed to the function by its caller 
(sometimes, to accomplish its task, a function needs to have some val- 
ues passed to it). Each argument is defined in the form <type> <name> 
where <type> is 'int' or 'str', and <name> is the name it should be 
called by. At present, a function is not allowed to have more than 12 
values passed to it. 


<variable_def> is a variable definition, as described in the above 
section on that topic. Any number of variables may be declared at this 
part of the function. All such variables will be local variables and 
available only to this function. 


<statement> is an actual line of code. There may be as many lines of 
statements in the function as needed. The format of a statement is de- 
scribed below. First though, here is an example of a complete func- 
tion: 


max ( int a, int b ) 


{ 


int result; 


if (a > b) 
result = a; 
else 
result = b; 


return result; 


} 


This function returns the larger (maximum) of the two values passed to 
it. It could have been written much more simply (without the use of 
the variable), but was written this way so that all the function ele- 
ments would be there. 


3.4 Statements 


C d: d: d: d d da: d d: d da dh: dh dh: dh dh dh: dh: dh: dh dh: dh: dh: dh: dh dh: dh: dh: dh dh: dh: dh dh: d da: dh: d A Aa d 
ed: d d d d d: d d d d: d d d: d d: da d d d d: da d: d da d d A A A 


A statement is the basic element of code. A statement ALWAYS ends with 
a semicolon character (;). In any location where a statement is ac- 
ceptable, you may use a group of statements, by enclosing them all in 
curly braces (more on this below). There are many types of statements, 
including: expression, if, while, do...while, for, return, break, con- 
tinue, and goto statements. Each type has several different parts. 
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3.4.1 The Expression statement 


The 'expression' statement is the simplest and most common type of 
statement. Its format is 


<expression>; 
where <expression> is any expression. Example are: 


result = 20; 

password = "Beef"; 
pause(20); 

num = 20 * max(a, b); 


Do not forget the semicolon character at the end of the statement. If 
you do, the compiler will think that the next statement is part of the 
current one, and will report some unexpected error. 


3.4.2 The If statement 


An 'if' statement is used when a statement or group of statements 
should be evaluated only if a condition is true. The format for an 
'if' statement is as follows: 


if (<expression>) 
<statement> 


<statement> is any statement as described above and below (that is, an 
expression, if, while, do...while, for, return, break, or continue 
statement), and will only be executed if <expression> evaluates to 
non-zero. By using curly braces around them, a whole group of state- 
ments may be conditionally evaluated. Some examples are: 


if (result == -1) 
prints("ERROR!"); 


if (num_tries > maximum) 
return 0; 


if (month > 10 && day < 20) 


clear(); 
prints("In range."); 
return 1; 


} 


An alternate form of the if statement is: 


if (<expression>) 
<statement1> 

else 
<statement2> 


In this case, if <expression> evaluates to non-zero (TRUE), 
<statement1> is executed, otherwise <statement2> is executed. Again, 
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multiple statements may be used instead by grouping them in curly 
braces. Some examples are: 


if (stat == -1) 
prints("Error status returned."); 
else 


prints("Function finished without problems."); 
if (level < 10) 


alarm(1); 
prints("Warning!"); 


else 
prints("Everything's ok."); 


Since the statement to be executed conditionally can be of any type, 
that means that any number of if statement can be nested if needed. 
For example: 


if (num < 10) 
if (!error) 
if (read != 0) 
return 1; 


This also means that something like the following is legal: 


if (value == 10) 
do_this(); 

else if (value == 100) 
do_that(); 

else if (value == 1000) 
do_something_else(); 

else 
do_whatever(); 


What is really happening here is that each if statement is being 
nested after the else portion of the previous one. The above example 
could also be written as: 


if (value == 10) 
do_this(); 
else 
if (value == 100) 
do_that(); 
else 
if (value == 1000) 
do_something_else(); 
else 
do_whatever(); 


Any amount of nesting is theoretically legal, but the compiler does 
have a limit due to memory constraints. 


While you may write the code in any way which suits you, it is recom- 
mended that you use indenting, for clarity. Indenting your code at the 
proper places makes it a lot easier to read. 
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A very common error to watch out for is accidentally placing a semi- 
colon after the parenthesis ending the expression. For example, if the 
following is run: 


if (num == 10); 
prints("Num is equal to 10); 


the string would always be printed, no matter what num was equal to. 
This is because the semicolon after the parenthesis ending the expres- 
sion signifies the end of the statement. In the above case, it would 
just be a null (empty) statement. 


3.4.3 The While statement 


The while statement is used to loop continuously while a certain con- 
dition is true. It has the form 


while (<expression>) 
<statement> 


<statement> would continue to be repeated over and over while 
<expression> evaluated to non-zero (TRUE). Note that if the expression 
evaluates to © (FALSE) from the beginning, the statement will never be 
executed. Again, multiple statements may be used by surrounding them 
in curly braces. A few examples are: 


while (stat != -1) 
stat = myfunc(); 


while (num < 100) 
printn(num); 
prints(""); 


num = num + 1; 


} 
while (1) 


if (func1()) 
return 0; 


func2(); 


Again, be careful to not place a semicolon after the parenthesis end- 
ing the expression. 


3.4.4 The Do...While statement 


The do...while statement is similar to the while statement and has the 
form: 


do 
<statement> 
while (<expression>); 
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<statement> will be executed at least once and will continue to be ex- 
ecuted repeatedly until the expression becomes 0 (FALSE). A few exam- 
ples are: 


do 

stat = func1(); 
while (stat != -1); 
do 


prints("hello"); 
num = num + 1; 


} 
while (num < 100); 


3.4.5 The For statement 


The for statement is used to loop continuously while a certain condi- 
tion is true. The advantages over the while statement is that a count 
variable can be initialized and incremented quite easily. The for 
statement has the form: 


for (<expression1>; <expression2>; <expression3>) 
<statement> 


The first expression is the one that should initialize the count vari- 
able. For example, if you wanted to count from 1 to 100, and were 
keeping the count in a variable called 'num', the first expression 
would be 'num = 1'. The second expression is the conditional test. As 
long as it evaluates to non-zero (TRUE), the statement will be exe- 
cuted. Following the above example, this expression would be 

'num < 100'. The third expression is the one that is used to increment 
the count variable. For the above example, it would therefore be 

'num = num + 1'. This for statement differs in format from that in 
most other languages, but doing it this way is actually gives the pro- 
grammer a lot of power and flexibility. Note that any of the expres- 
sions can be left empty, in which case they evaluate to non-zero 
(TRUE). Some examples are: 


for (count = 0; count < 100; count = count + 1) 


{ 
printn(count); 
prints(""); 


for (c = 1000; c > 0; c=c - 1) 
do_this(c); 
The following would execute an infinite loop: 


for (55) 
prints("Hello!"); 


Note that there is really no restriction on what the expressions are. 
For example, the following is quite legal: 
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for (c = num = 0; c < 100 && stat != -1; c = c + 1) 


stat = func(num); 
num = func2(); 


} 


The statements would only be executed if c was smaller than 100 and 
stat didn't equal -1. 


3.4.6 The Return statement 


At some time, every function must be exited. If the end of the func- 
tion is reached, control will automatically return to the calling 
function. Very often however, it is necessary to leave a function 
somewhere while only halfway through it, perhaps based on a condi- 
tional test. As well, it is often necessary that a function returns a 
value to the caller. The format of the return statement is: 


return <expression>; 


If the return statement is encountered anywhere in the function, con- 
trol immediately returns to the function that called this function. 
The expression is the value that should be returned. If no expression 
is supplied, a dummy value is returned. The expression should match 
they type of value that the caller of this function is expecting. That 
is, if an 'int' type is expected, the expression should resolve to an 
integer value. If a 'str' type is expected, the expression should re- 
solve to a string value. Due to memory constraints, a local string 
variable may NOT be returned from a function. Some examples are: 


return; 

return 1; 

return level; 

return (sum + 25); 
return "hello"; 
return (func() + 20); 


Notice that when a complex expression is returned it is usually sur- 
rounded by parentheses. This is done only for clarity and is not nec- 
essary. Also, it should be clear that what is returned is not the ex- 
pression but what it evaluates to. 


3.4.7 The Break statement 


Often while using a looping statement (while, do...while, for), it is 
necessary to break out of (exit) the loop. The break statement serves 
this purpose. When the break statement is encountered, execution of 
the smallest while, do...while, or for loop is terminated, and execu- 
tion continues immediately after the terminated loop statement. It is 
an error for a break statement to appear outside of a loop. The format 
of the break statement is: 


break; 


For example, assuming you had the following code: 
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int num = ®; 
while (1) 


num = num + 1; 
if (num > 100) 
break; 


prints("Done"); 


Ordinarily, since there will always be a non-zero (TRUE) value in the 
conditional part of this while statement, it would execute forever. 
However, when the 'num' variable is > 100, the break statement is exe- 
cuted to exit from the loop, at which point the next statement would 
be executed (the function call to prints). 


3.4.8 The Continue statement 


The continue statement is used within a loop (while, do...while, or 
for statement). The continue statement has the form: 


continue; 


It is illegal for a continue statement to appear outside of a loop 
body. When a continue statement is encountered, program control is im- 
mediately transferred to the end of the body of the innermost en- 
closing while, do...while, or for statement. The effect in a while or 
do...while statement is that the condition part of the while or 
do...while statement is evaluated, and the next iteration of the loop 
occurs. For example: 


num = 0; 
while (num < 100000) 
{ 
num = num + 1; 
if (num > 100) 
continue; 
prints("Hello"); 


The effect of the continue statement in the above loop would be that 
'Hello' would only be printed while 'num' was smaller or equal to 100, 
as the continue statement is executed when num is bigger than 100, 
which causes the rest of the loop body to be skipped. An example for 
statement would be: 


for (num = 0; num < 100000; num = num + 1) 


if (num > 100) 
continue; 
prints("Hello"); 


The effect in this case would be the same. While 'num' is smaller or 
equal to 100, the entire loop body executes. If 'num' is greater than 
100 however, the continue statement is executed. This causes the rest 
of the loop body to be skipped, so the 'Hello' is then not printed. 
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3.4.9 The Goto statement 


The goto statement is used to branch (jump) from one place to another, 
within a function. The use of goto statements is considered bad style. 
They can make code very hard to understand, and are in fact almost 
never necessary. For example, Telix is written mainly in the C lan- 
guage, which has a goto statement, yet except for a few pieces of pre- 
written code, the goto statement was never used nor needed. On the 
other hand, used very sparingly and properly, it can sometimes make 
some code clearer and perhaps faster. The goto statement consists of 
two parts, the 'label' or marker, which is where execution will jump 
to, and the actual goto itself. A label is defined in the form 


<identifier>: 


where <identifier> follows the same rules as for variable names. Note 
that a colon follows the name, not a semicolon. The colon character 
must immediately follow the label name, with no intervening spaces. A 
label does not have to be on a line by itself, and is not considered a 
statement by itself. The goto takes the form 


goto <label>; 


where <label> is a label elsewhere in the function defined as de- 
scribed above. Execution of the script will immediately continue fol- 
lowing the label. 


An example is: 


start: 
prints("Hello"); 
goto start; 


This would print the word "hello" over and over, forever. There is no 
restriction on the placement of a label, so the above can be written 
as: 


start: prints("Hello"); 
goto start; 


As mentioned above, there are usually better ways than using a goto 
statement. For example: 


int i = 0; 

do 

i=i+t]1; 
while (i < 100); 


is clearer than the equivalent: 


int i = 0; 

Loop: 

ToS + E E 
if (i < 100) 
goto loop; 


Telix v3.22 - SALT Programming Program Structure 18 


One good use of a goto statement is to get out of a deeply nested 
while statements, without having to do a lot of extra checking. 
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4. BUILT-IN FUNCTIONS 


Telix's SALT has quite a large number of built-in functions. These 
functions are called just as you would call your own SALT functions. 
Each function does a certain task (print something to the screen, ma- 
nipulate strings, access disk files, etc.). Each function is called 
with parameters in a certain format and returns an integer or string 
value (the return value does not have to be used and is often a dummy 
variable). 


The following pages contain a quick listing of the functions by type 
followed by a complete description of each function, in alphabetical 
order. The complete reference contains for each function, a summary of 
the calling format, a description of what it does, and the return 
value of the function are all given. An example of actual usage of the 
function is often given. Note that the examples are fragments of pro- 
gram code for the most part, and may not explicitly declare all needed 
variables. So that you may find related functions, each function de- 
scription has a 'See Also' section, which lists related functions. 
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4.1 Quick Listing of Functions by Type 


99999 99999999999 999999999999 999999999999 
99999 999999999999 9999999999999 


Video Operations 


box, cursor_onoff, clear_scr, getx, gety, gotoxy, printc, printn, 
prints, printsc, pstra, pstraxy, scroll, status_wind, update_term 


String Handling 

copychrs, copystr, delchrs, gets, getsxy, inschrs, itos, setchr, 
setchrs, stoi, strcat, strchr, strcmpi, strlen, strlower, strmaxlen, 
strpos, strposi, strupper, subchr, subchrs, substr 


Character Handling 


isascii, isalnum, isalpha, iscntrl, isdigit, islower, isupper, 
tolower, toupper 


Comm Port Operations 

carrier, cinp_cnt, cgetc, cgetct, cputc, cputs, cputs_tr, flushbuf, 
get_baud, get_datab, get_parity, get_port, get_stopb, hangup, 
set_cparams, set_port 

File and File I/O Operations 

fclearerr, fclose, fdelete, ferror, feof, fflush, fgetc, fgets, 
fileattr, filefind, filesize, filetime, fnstrip, fopen, fputc, fputs, 
fread, frename, fseek, ftell, fwrite 

Keyboard Operations 

inkey, inkeyw, keyget, keyload, keysave, keyset 


Date/Time and Timer Operations 


curtime, date, tsec, tday, thour, time, time_up, timer_free, 
timer_restart, timer_start, timer_total, tmin, tmonth, tyear 


File Transfers, Capture, Printer, and Usage Log 

capture, printer, receive, send, transtab, usagelog, ustamp 
Script Management 

call, calld, delay_scr, is_loaded, load_scr, unload_scr 
Input String Matching 


track, track_addchr, track_free, track_hit, waitfor 
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Other Functions 


alarm, chatmode, delay, dial, dos, dosfunction, exittelix, helpscreen, 
loadfon, newdir, redial, redirect_dos, run, send_brk, set_defprot, 
set_terminal, show_directory, terminal, tone 


Telix v3.22 - SALT Programming Built-in Functions 22 


4.2 Complete Function Reference 


9299999 


99999 99999999999 999999999999 9H9H 
92999999999 929929999999 


ALARM 
SSSSSSSSSSSSSSSSSSSS SSS S535 SARRRRRRRS 
© Summary 

alarm(int <seconds>); 

® Description 


The alarm functions sounds an alarm for a a duration in seconds given 
by <seconds>. 


€ Return Value 

The <seconds> argument is returned. 
€ See Also 

tone, _alarm_on, _sound_on 

€ Example 


while (!inkey()) 
alarm(1); 


BOX 


99999 99999999999 999999999999 99999999999 
9999999999 999999 9999999999999 


€ Summary 


box(int <x>, int <y>, int <x2>, int <y2>, int <style>, int <hollow>, 
int <color>); 


% Description 


The box function is used to create a box on the screen. The box will 
have an upper left hand corner of <x>,<y> and a lower right hand cor- 
ner of <x2>,<y2>. The box must fit within the confines of the screen. 
<color> is the color to use in drawing the box. If <hollow> is a non- 
zero (TRUE) value, the inside of the box is not cleared. <style> se- 
lects what kind of box to draw, as follows: 
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Spaces 

Single lines 

Double lines 

Single vertical lines, double horizontal lines 
Double vertical lines, single horizontal lines 


E GM GG 


If <style> is any other value, that character is used to construct the 
sides of the box. 


Return Value 
None. 

€ See Also 
scroll 

€ Example 


box(10, 10, 70, 20, 1, 0, 112); // draw box in inverse color 


CALL, CALLD 


999 9999999999999 999999999999 999999999999 
9999999999999 999999 99999999999 


€ Summary 
call(str <scriptname>, <argi>, <arg2>, <arg3>, ...); 
calld(str <scriptname>, <argi>, <arg2>, <arg3>, ...); 


% Description 


The call function is used when one script file must call (jump into 
and then return from) another. <scriptname> is the name of the script 
file to call. If no extension is given, .SLC is assumed. <argl> 
through <argn> are the arguments or parameters to be passed to the 
'main' function of the called script. The value returned is the value 
returned by the 'main' function of the called script, and can be an 
integer or a string value, although the called script can not return 
string variables local to itself. If the script file to be called is 
already in memory because it was previously loaded and made resident, 
or it is still executing from a previous call, it is not released but 
instead the memory image is used. This means that global variables 
will have whatever values a previous run through left in them. 


The calld function is exactly the same as the call function, except 
that even if an image of the indicated script file is already in mem- 
ory, a new copy is still loaded from disk. This ensures that global 
variables within the script will be set as defined in the source file, 
and that there will be enough stack space, but requires more memory 
and is slower. 


€ Return Value 


An integer or string value representing the value returned by the main 
function of the called script file. This value must not be a string 


Telix v3.22 - SALT Programming Built-in Functions 24 


variable defined within the called script, for memory reasons. if the 
indicated script can not be found or loaded, a value of -1 is re- 
turned. If the called script is aborted by the user, a value of -1 is 
returned. 

See Also 

load_scr, unload_scr, is_loaded 

€ Example 

stat = call("TEST"); 


if (stat == -1) 
prints("Called script could not be loaded or was aborted!"); 


CAPTURE 
9999999 9999999999999 999999999999 99999999 
999999999999 d 999999 99999999999 

€ Summary 

capture(str <filename>); 

% Description 

The capture function is used to open, close, pause, and unpause the 

Telix capture file. Depending on what the string variable <filename> 


contains, different actions will take place. 


If <filename> contains a valid filename (which can include a path), 
Telix opens and starts capturing data to that file. 


If <filename> is "*CLOSE*", and the capture file is currently open, it 
is closed. 


If <filename> is "*PAUSE*", and the capture file is currently open, it 
is paused. 


if <filename> is "*UNPAUSE*", and the capture file is currently open 
and paused, it is unpaused. 


If <filename> is an empty string (""), Telix takes the same action as 
if the user had pressed Alt-L while in terminal mode (which will de- 
pend on whether the capture file is currently open or closed). 


© Return Value 


A value of -1 is returned if there is a problem performing the indi- 
cated function, otherwise a non-zero (TRUE) value is returned. 


€ See Also 


printer, capture_stat, _capture_fname 
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€ Example 


if (capture("TELIX.CAP") == -1) 
prints("Error opening capture file!"); 


capture("*PAUSE*"); 


capture("*UNPAUSE*"); 
capture("*CLOSE*"); 


CAPTURE_STAT 


2222229292292 9992999299929999999999999999 
999999999999 9999999999999 99999 

% Summary 

capture_stat(); 


% Description 


The capture_stat function returns an integer value representing the 
current status of the capture file, as follows: 


0 Capture File is closed 
1 Capture File is open 
2 Capture File is open and paused 


€ Return Value 
An integer values as described above. 
€ See Also 


capture, usage_stat 


CARRIER 
9999999 9999999999999 999999 999999999999 99 
999999999 9G 999999999 99999999 OO 

% Summary 

carrier(); 

% Description 


The carrier functions returns a non-zero (TRUE) value if the Carrier 
Detect signal coming from the modem is on (high), otherwise it returns 
a zero (FALSE) value. Note that some modems by default override the 
real state of the signal and always send a high. For this function to 
work, the modem must be told to supply the real signal. This function 
may be used to check if Telix is connected to a remote service over 
the modem, as the Carrier Detect signal should be on if there is a 


connection. Note that if you are connecting two computers via a null- 
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modem cable, the value returned will depend on the wiring of the cable 
being used. 


Return Value 


non-zero (TRUE) or zero (FALSE) based on the state of the Carrier De- 
tect signal. 


€ Example 
if (carrier()) 


prints("We are online."); 


CGETC, CGETCT 
999999999 9999999999999 999999999999 999999 
999 999999999999 9999999999999 00 
€ Summary 
cgetc(); 
cgetct(int <timeout>); 
% Description 
The cgetc function returns the first character waiting in the received 
data communications buffer. If there are no characters in the buffer, 
a value of -1 is returned. The cinp_cnt function may be used to see if 
there are any chars waiting in the buffer. 
The cgetct functions returns a character from the communications port, 
waiting up to <timeout> tenths of a second for it to arrive. If a 
character is already waiting in the communications buffer, it is imme- 
diately returned. If no character is received within the timeout pe- 
riod, a value of -1 is returned. 
€ Return Value 
An integer value as described above. 
€ See Also 
cinp_cnt 
€ Example 
if (cinp_cnt()) 
chr = cgetc(); 


if ((chr = cgetct(100)) == -1) 
prints("Timeout!"); 
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CHATMODE 
9999999 9999999999999 999999999999 99999999 
9999999 9999999999999 99999999 00 
€ Summary 
chatmode(int <echo_remote>) ; 
% Description 
The chatmode function enters the chat mode as if the user had pressed 
Alt-Y while in terminal mode, If <echo_remote> is non-zero (TRUE), 
characters typed by the remote user are echoed back to him/her, other- 
wise they are not. The echo feature is for use in Host Mode 
implementations. 


€ Return Value 


None. 


CINP_CNT 
SSSSSSSSSSSSSSSSSSSSSSS SSS 555 MN! 

$ Summary 

cinp_cnt(); 

ê Description 


The cinp_cnt function returns the number of characters waiting in the 
received data communications buffer. 


€ Return Value 

An integer value as described above. 
€ See Also 

cgetc 

ê Examples 


if (cinp_cnt() > 10) // if more than 10 chars waiting 


handle_stuff(); // 00 action 
while (!cinp_cnt()) // loop until no chars available 
if (cinp_cnt()) // if something available, get it 


c = cgetc(); 
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CLEAR_SCR 
sssesseesesssssseessssssssssssee eee eeees 

$ Summary 

clear_scr(); 


% Description 


The clear_scr function clears the screen and places the cursor in the 
upper Left corner at position 0,0. 


€ Return Value 
None. 
€ See Also 


scroll 


COPYCHRS 
SSSSSSSSSSSSSSSSSSSS SSS SSS 555 MN! 

$ Summary 

copychrs(str <source>, str <target>, int <pos>, int <count>); 


% Description 


The copychrs function copies a number of characters from one string 
into another, Characters from the string <source> are copied into the 
string <target> at the position <pos> (note that SALT string offsets 
start at 0, not 1 as in some languages). until <count> characters are 
copied. Only as many characters as will fit in <target> are copied. 


This function is very similar to substr, except that it is not string 
oriented, and does not stop copying characters when a © value is en- 
countered. 


The substr function copies a portion of one string to another. Char- 
acters from position <pos> in string <source> are copied until into 
string <target> (note that SALT string offsets start at 0, not 1asin 
some languages). Characters are copied until a © (NULL) value is en- 
countered (normally at the end of every string), or <max> characters 
are copied. A © (NULL) is always copied at the end of the target 
string. The 0 does not count as part of the <max>. Only as many char- 
acters as will fit in <target> are copied. 


© Return Value 


None. 
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€ See Also 


copystr, subchrs, substr 


COPYSTR 
2222222929999 
2922292292299 92999999999 999999 

% Summary 

copystr(str <source>, str <target>, int <pos>, int <count>); 

% Description 

The copystr function copies one string into another at a certain po- 

sition. Characters in string <source> are copied into string <target> 

at position <pos> (note that SALT string offsets start at 0, not 1 as 
in some languages). Characters are copied until a © (NULL) value is 
encountered (normally at the end of every string), or <max> characters 
are copied. A © (NULL) is always copied at the end of the target 
string. The © does not count as part of the <max>. Only as many char- 
acters as will fit in <target> are copied. 

© Return Value 

None. 


€ See Also 


copychrs, substr, subchrs 


CPUTC 
9999 999999999999 9999999999999 99999999999 
99999999 9999999999 999999999999 

% Summary 

cputc(int <character>); 


% Description 


The cputc function sends <character> to the communications port. This 
is the ASCII value of the character to be sent. 


Return Value 


A non-zero (TRUE) value is returned unless the character can not be 
sent for some reason, in which case a value of -1 is returned. 


See Also 


cputs 
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€ Example 
cputc('A'); 
cputc(27); // send Escape to the comm port 
cputc('^M'); // send Ctrl-M (Carriage Return) 


cputc(inkeyw()); 


CPUTS 
sssessessesssssseessssssssessse tees eeees 

$ Summary 

cputs(str <outstr>); 

® Description 


The cputs function sends the passed string out over the modem port. A 
Carriage Return and Line Feed are NOT added after the string. 


€ Return Value 
None. 

€ See Also 
cputs_tr 

€ Example 
cputs("Good-bye"); 


str password[] = "mypass"; 
cputs(password); 


CPUTS_TR 
9999999 9999999999999 999999999999 99999999 
9999999 9999999999999 99999999 00 

€ Summary 

cputs_tr(str <outstr>); 

% Description 

The cputs_tr function sends the passed string out over the modem port, 

but pays attention to two output string translation characters, ^ and 

-, described in the Telix manual. This function is really only useful 

for sending the modem control strings that the user has defined in the 


Configuration Menu. 


Return Value 


None. 
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€ See Also 
cputs 
€ Example 


cputs_tr(_modem_init); 
cputs_tr("good-bye~yes4M") ; 


CURSOR_ONOFF 
999999999 9999999999999 999999999999 999999 
999999999 99999999999 9999999999 

% Summary 

cursor_onoff(int <state>); 

% Description 

The cursor_onoff functions turn the blinking cursor on or off (makes 

it disappear or reappear), depending on whether state is non-zero 

(TRUE) or zero (FALSE). 

© Return Value 


None. 


CURTIME 
9999 999999999999 9999999999999 9999999 d da da d 
99999999 9999999999 999999999999 
€ Summary 
curtime(); 
% Description 
The curtime function returns the current date/time as the number of 
seconds since Jan 1, 1970. A date/time value in this format is used by 
many SALT functions. 
Return Value 
An integer value as described above. 
See Also 


date, time, tyear, tmonth, tday, thour, tmin, tsec 


€ Example 


// Print the current date 
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int t; 
str s[64]; 


t = curtime(); 


date(t, s); 
prints(s); 


DATE 
9999999 9999999999999 999999999999 99999999 
999999999 9999999999999 999999 00 
% Summary 
date(int <timeval>, str <buffer>); 
% Description 
The date function writes out a date in <buffer> in the form mm/dd/yy, 
dd/mm/yy, or yy/mm/dd (which is based on the system variable 
_date_format). <timeval> is the date, represented as the number of 
seconds since Jan 1, 1970. Time values in this form are returned by 
the curtime and filetime functions, among others. 
Return Value 
None. 
See Also 
time, curtime, filetime 
@ Example 
str s[16]; 
printsc("The current date is "); 


date(curtime(), s); 
prints(s); 


DELAY, DELAY_SCR 
28322322223232422327223223832 72022120225. 
% Summary 
delay(int <duration>); 
delay_scr(int <duration>); 
% Description 
The delay function pauses Telix for a length of time specified in 


tenths of a second by <duration>. During this pause, everything is 
shut off except the asynchronous reception of characters from the comm 


port. 
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The delay_scr function pauses only the execution of the current script 
file for the indicated duration. During that time, characters coming 
in from the serial port are printed on the terminal screen, while user 
keystrokes are also processed. 

€ Return Value 


The <duration> argument is returned. 


DELCHRS 
999999999999 99999999999 9999999999999 d dada d 
99999999 9999999999 999999999999 
€ Summary 
delchrs(str <s>, int <pos>, int <num>); 
% Description 
The delchrs function is used to remove or delete a number of charac- 
ters in a string at a certain position. <s> is the string to handle. 
<pos> is the position at which <num> characters will be deleted (note 
that the first characters in a SALT string has the position 0). Re- 
maining characters in the string are be shifted left. 
© Return Value 
None. 
€ See Also 
inschrs 
€ Example 


// remove all but the first and last characters in a string 


str s[] = "0123456789"; 
delchrs(s, 1, strlen(s) - 2); 


DIAL 
EEES III 3333333333535 MN! 

$ Summary 

dial(str <dialstr>, int <maxtries>, int <no_link>); 

® Description 


The dial function dials the entries specified in <dialstr>. The en- 


tries should be entered in the same format as used when typing entries 
in the dialing directory. If <dialstr> is empty (""), the dialing di- 
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rectory is displayed. <maxtries> is the maximum number of dialing at- 
tempts. For example, if the string contains one entry, and <maxtries> 
is equal to 5, Telix will attempt to dial the number 5 times. If five 
entries are indicated, and <maxtries> is equal to 5, each number will 
only be attempted once. If <maxtries> is 0, dialing will continue un- 
til a connection is established. If an entry is connected to, and has 
a linked script file attached, that script will be run, unless 
<no_link> is non-zero (TRUE). 


€ Return Value 


If there was a connection, the dial function returns the entry number 
of the entry which was connected to (or 1 if a manual number was di- 

aled). If there was no connection established, © is returned. If the 

<dialstr> has a bad format, -1 is returned. 


Also, when a connection is successfully established, the entry number 
of the entry connected to is placed in the system variable 
_entry_enum, while the name of the entry connected to is placed in the 
system variable _entry_name. 


€ See Also 


redial 
_entry_enum, _entry_name 


€ Example 


int stat; 

dial("10 15", 0); 
dial("m967-1111", 5); 

stat = dial(number_list, 0); 


DOS 
999999999 999999 9999999999999 99999999999 
99999 9999999999999 99999999999 

€ Summary 

dos(str <command>, int <mode>); 


% Description 


The dos function calls the DOS command interpreter (usually COM- 
MAND.COM, and gives it the passed command string. If the <command> 
string is empty (""), Telix will drop into a DOS shell, as if the Alt- 
J command had been executed. Make sure that if you specify a command 
or program that expects user input you are on hand to give it. The 
<mode> argument specifies several options, as follows: 


0 Original screen is restored when command is completed. 

1 When command is completed, the user is prompted to press a 
key and screen is restored as soon as it is pressed. 

2 Original screen is not restored when command is completed 


Telix v3.22 - SALT Programming Built-in Functions 35 


This function is very similar to the run function. It should be used 
when an internal DOS command is needed or a DOS shell is needed, oth- 
erwise run is preferable as it uses less memory and executes faster. 
© Return Value 

The dos function returns a -1 if the command processor can not be 
found or there is not enough memory to load it, otherwise a 0 is re- 
turned. 

€ See Also 

run, dosfunction 


€ Example 


dos("copy a:*.* c:", 1); 


DOSFUNCTION 


999999999999 9999999999 99999999999 9999H 9 
999999999999 999999 999999999999 

% Summary 

dosfunction(); 


% Description 


The dosfunction function calls up the 'DOS Functions' menu, as if the 
user had pressed Alt-F while in terminal mode. 


Return Value 
None. 
See Also 


dos, run 


EXITTELIX 
OE d d d d d da d dh dh dh: dh: dh: dh: dh: dh: dh: dh dh dh da dh d da dh d 
9999999 d d da da dh: dh: dh: dh: dh: dh: dh d da d d da da da da da da A A 

€ Summary 

exittelix(int <returncode>, int <hangup>); 


% Description 


The exittelix function closes any currently open log file, and exits 
Telix to DOS, as if the user had pressed Alt-X while in terminal mode. 


The <returncode> argument is the value that should be returned to DOS. 
This value can be read by whatever called Telix (e.g., a batch file 
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using the errorlevel command). The <hangup> option affects what hap- 

pens if Telix is online. If it is set to non-zero (TRUE), Telix will 

hang-up before returning to DOS, otherwise the connection will not be 
disturbed. 

© Return Value 


Since this functions causes Telix to terminate, there is never any re- 
turn from it. 


€ Example 

exittelix(0, 1); 

exittelix(100, 0); 

FCLEARERR 
9999 999999999999 9999999999999 99999999999 
999999999999 9999999999 99999999 

% Summary 

fclearerr(int <fh>); 

% Description 

The fclearerr function clears the error flag assigned to the open file 

represented by file handle <fh>. It also clears the End Of File flag 

for that file as well. 

€ Return Value 

None. 

€ See Also 

ferror, feof 


€ Example 


int f; 
f = fopen("test.dat", "r"); 


if (ferror(f)) 

fclearerr(f); 

FCLOSE 
292299229292 929999999999 99999999999 999999 
29229999992 99999999999 999999999 

% Summary 

fclose(int <fh>); 


% Description 


The fclose functions closes the file represented by the file handle 
<fh>, which must previously been opened for reading or writing with 
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the fopen function. If the file was opened for writing, any data which 
is still buffered and waiting to be written out to disk is written be- 
fore the file is closed. 

© Return Value 

A return value of -1 indicates a problem closing the file. 

€ See Also 

fopen 


€ Example 


int f; 
f = fopen("test.dat", "w"); 


fclose(f); 


FDELETE 


9999999 9999999999999 99999999 999999999999 
9999999 9999999999999 9999999999 

% Summary 

fdelete(str <filename>); 

% Description 

The fdelete function is used to delete a disk file from within a 

script. <filename> is the name of the file to delete. A full drive and 

path may be specified as part of the filename, and case is not signif- 
icant, but wildcard characters (* or ?) may NOT be part of the file- 

name. 


© Return Value 


A value of -1 is returned if there is a problem deleting the file, 0 
otherwise. 


€ See Also 
frename 
€ Example 


fdelete("C:\UTIL\TLX\TELIX.CAP"); // delete an old capture file 


FEOF 
99999 99999999999 999999999999 999999999999 
9999999999999 999999999999 99999 


€ Summary 


feof(int <fh>); 
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% Description 


The feof function determines if the file position for the open file 
represented by the file handle <fh> is at the end-of-file position. 


© Return Value 


A non-zero (TRUE) value is returned if the file position is at the end 
of the file. 


€ See Also 

ferror 

€ Example 

int f, chr; 

f = fopen("test.dat", "r"); 

while ((chr = fgetc(f)) != -1) // print contents of file 
printc(chr); 

if (feof(f)) 
prints("Reached end of file."); 


else 
prints("Error reading file"); 


FERROR 
9999999 999999999 999999999999 d 
9999999 9999999999999 99999999 00 
% Summary 
ferror(int <fh>); 
% Description 
The ferror function checks the error flag for a file represented by 
the file handle <fh>. The error flag stays set until it is cleared 
with fclearerr or the file is closed. 
€ Return Value 
A non-zero (TRUE) value is returned if the file's error flag is set. 


€ See Also 


fclearerr, feof 


€ Example 
int f; 
f = fopen("test.dat", "r"); // open file only for reading 


fputs("This should set the error flag!", f); 
if (ferror(f)) 
prints("Error writing to file!"); 
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FFLUSH 
9999999 9999999999999 99999999 d 
99999 9999999999999 9999999999 9OO 
€ Summary 
fflush(int <fh>); 
% Description 
The fflush function flushes the buffer associated with the file rep- 
resented by file handle <fh>. If the file is opened for writing, any 
characters in the buffer are written. If the file is opened for read- 
ing, the buffer is cleared. 
© Return Value 
A value of -1 is returned if there is a problem flushing the buffer. 


€ See Also 


fopen, fclose 


FGETC 
9999999 9999999999999 99999999 999999999999 
9999999 9999999999999 9999999999 

€ Summary 

fgetc(int <fh>); 

% Description 

The fgetc function returns the next character from the file rep- 

resented by the file handle <fh>. The file must have been opened for 

reading or from reading and writing, using the fopen function. 


€ Return Value 


Returns the character read if successful, or -1 if the end of the file 
has been reached or an error is encountered. 


€ See Also 


fopen, fputc 


€ Example 

int f; 

f = fopen("test.dat", "r"); 

while (!feof(f)) // print all the characters in the file 


printc(fgetc(f)); 
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FGETS 
OCE d d d d d da d dh: dh: dh: dh: dh: dh: dh: dh dh dh dh dh dh dh dh d dh dh dh d 
99999 d d d d d d dh: dh: dh: dh: dh: dh: d d: da d da da da da da da Aa A A 
€ Summary 
fgets(str <buffer>, int <n>, int <fh>); 
% Description 
The fgets function reads characters from the open file indicated by 
the file handle <fh> into the string variable <buffer>. Reading stops 
when a newline (Line Feed) character is read, and end-of-file is en- 
countered, a read error occurs, or <n> characters have been read. The 
Line Feed character (and the Carriage Return that usually precedes it 
on MS-DOS systems) is not kept as part of the string. 
Important: The SALT implementation of the fgets() function differs 
from the C language function of the same name. While both implemen- 
tations read until the Line Feed character, C keeps that character as 
part of the input string, while SALT doesn't. This change was made be- 
cause in almost every case, the Line Feed is not needed, and would 
otherwise have to be manually stripped by the script after every read. 
Return Value 


A value of -1 is returned if there is a read error, or if there is an 
end-of-file before any characters can be read. 


See Also 

fopen, fputs 

€ Example 

int f; 

str s[100]; 

f = fopen("test.dat", "r"); 

while (!feof(f)) // print out contents of text file 


fgets(s, 100, f); 
printsc(s); 


FILEATTR 
9999 999999999999 9999999999999 99999999999 
999999999999 999999 999999999999 

€ Summary 

fileattr(str <filespec>); 


% Description 


Under the MS-DOS file system, files have a certain attributes which 
can determine their functions or the way certain things behave. For 


example if a file has the 'hidden' bit set as part of its attribute 
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byte, when you do a DOS dir command, the file is not shown. Similarly, 
if a file has the read only bit set, you may not overwrite it. 


The fileattr function returns an integer value representing the at- 
tributes of a specified file. <filespec> is the name of the file and 
may include a drive and directory portion, as well as the DOS wildcard 
characters * and ?. 


The value returned is a total of the following attributes. 
1 Read only file. 


2 Hidden file. The file is not listed when the DOS dir command 
is executed. 


4 System file. The file is not listed when the DOS dir command 
is executed. 


8 Volume label. This is the volume name of the disk. 
16 Subdirectory. This is a subdirectory name. 


32 Archive bit. This is set by DOS whenever a file has been 
written to and is then used by some backup software to check 
if a file has been modified since last backed-up. 


Each of these values is a certain bit in a byte. To test for the ex- 
istence of an attribute, the bitwise AND operator should be used. For 
example, the following fragment would check if the read only bit in an 
attribute is set: 


if (attrib & 1) 


If <filespec> is blank (""), then the attributes of the last file 
found with the filefind function is returned. Note that calling file- 
size or filetime in the meantime with a non-blank filename would in- 
stead make this call return the attributes of files found with those 
functions, as they use the same buffer. 


© Return Value 


An integer value representing the combined attributes of the indicated 
file is returned, or a value of -1 is returned if the indicated file 
could not be found. 


€ See Also 

filefind, filesize, filetime 
€ Example 

int attr; 

str filename[64]; 
gets(filename, 64); 


attr = fileattr(filename); 
if (attr & 6) // system _and_ hidden added together 
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prints("This file is marked as hidden and system"); 


FILEFIND 
9999 999999999999 9999999999999 9H9 
999999999999 999999 999999999999 

% Summary 

filefind(str <filespec>, int <attrib>, str <buffer>); 


% Description 


The filefind function is used to search for the existence of one or 
more files or disk directories. Filefind puts in <buffer> the name of 
the first file matching <filespec>, which may include a drive and path 
as well as a filename, and may use the DOS wildcard characters * and ? 
(e.g., "*.*", "C:\TELIX\TELIX.EXE", "SCRIPTS\TEST??.*"). <attrib> is 
the attribute (also see fileattr) which files must match. The at- 
tribute is obtained by adding certain values as follows: 


Normal files and read only files 
Hidden files 
System files 
Disk volume label 
6 Subdirectory 


HORANO 


If the attribute is 0, only normal (and read-only) files are found. If 
the volume label is selected, only volume labels will be returned. Any 
other selected attribute or combination (addition) of attributes re- 
sults in those files and all normal files being matched. 


when a matching file, directory, or volume name is found, it is put in 
<buffer> (note that the drive and path portion of filespec are not 
copied), and a non-zero (TRUE) value is returned. The size, date/time, 
and attributes of the matched file can be seen with the filesize, 
filetime, and fileattr functions, respectively. If no files matching 
the file specification are found, a zero (FALSE) value is returned. 


If <filespec> is blank (""), then filefind searches for the next 
matching file. Note that this will not work after an intervening call 
to filesize, filetime, or fileattr with a non-blank filename, as the 
same buffer is used for searches and to keep data. 

Return Value 


A non-zero (TRUE) value is returned if a file matching the speci- 
fication was found, otherwise a value of zero (FALSE) is returned. 


€ See Also 

filesize, filetime, fileattr 

€ Example 

// show all normal files in the current directory 


str buf[16], fspec[16] = "*.*"; 
while (filefind(fspec, 0, buf) != 0) 
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prints(buf); // show file found 

fspec = ""; // so we can continue searching for files 
} 
FILESIZE 


99999 d dh: d d: d da dh: dh: dh: dh dh dh: dh: dh: dh dh: dh: dh: dh dh dh: dh: dh: dh da: da: dh dh: d da: da: d A Aa A 
ed: d d d d: d d d d da: d d d: d d:d d d d: d: d d d da d: d A A A 


€ Summary 
filesize(str <filespec>); 
% Description 


The filesize function returns the size in bytes of the specified file. 
<filespec> is the name of the file and may include a drive and direc- 
tory portion, as well as the DOS wildcard characters * and ?. 


If <filespec> is blank (""), then the size of the last file found with 
the filefind function is returned. Note that calling filetime or 
fileattr in the meantime with a non-blank filename would instead make 
this call return the size of files found with those functions, as they 
use the same buffer. 


© Return Value 

An integer value representing the size of the indicated file is re- 
turned, or a value of -1 is returned if the indicated file could not 
be found. 

€ See Also 

filefind, filetime, fileattr 

€ Example 

str filespec[24] = "*.*", buf[12]; 

int size; 


siz = filesize("TELIX.EXE"); // get size of file TELIX.EXE 
// Add up size of all files int he current directory 


siz = 0; 
while (filefind(filespec, 0, buf) != 0) // until no more files 
{ 
siz = siz + filesize(""); // get size of last filefound file 
filespec = ""; // make sure filespec is "" on sub- 
// sequent calls to filefind to 
// continue searching for files 
} 
FILETIME 


C d: d: d: d d da: d d: d da dh: dh dh: dh dh dh: dh: dh dh dh: dh: dh: dh dh dh: dh dh: dh dh: dh: dh dh: d da: dh: d A Aa A 
99999 d: d: d d da da: d d d: d d: da: d: d da: d: da d: d da d d A A A 


€ Summary 


filetime(str <filespec>); 
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% Description 


The filetime function returns the date/time of the specified file. 
<filespec> is the name of the file and may include a drive and di- 
rectory portion, as well as the DOS wildcard characters * and ?. 


The values returned represents the file's modification date as the 
number of seconds since Jan 1, 1970. A date/time in this form can be 
used by the date, time, tyear, tmonth, tday, thour, tmin, tsec, and 
other functions. 


If <filespec> is blank (""), then the date/time of the last file found 
with the filefind function is returned. Note that calling filesize or 
fileattr in the meantime with a non-blank filename would instead make 
this call return the time/date of files found with those functions, as 
they use the same buffer. 


Return Value 


An integer value representing the date/time of the indicated file is 
returned, or a value of -1 is returned if the indicated file could not 
be found. 


See Also 
filefind, filesize, fileattr 
€ Example 


int time; 
str s[16]; 


time = filetime("TELIX.EXE"); 
if (time == -1) 
prints("'TELIX.EXE" could not be found!"); 
else 
{ 
printsc("TELIX.EXE was created at "); 
time(time, s); 
printsc(s); 
printsc(" on "); 
date(time, s); 
printsc(s); 


// this example assumes both files exist 
if (filetime("FILE1") < filetime("FILE2")) 
prints("FILE1 is older than FILE2"); 
else 

prints("FILE1 is newer than FILE2"); 
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FLUSHBUF 
99999999 99999999999 9999999999 99999 
999999999999 999999 999999999999 

€ Summary 

flushbuf(); 


% Description 


The flushbuf function flushes (throws away) any characters that may be 
waiting in Telix's remote input buffer. One use for this command is to 
get rid of unwanted line noise. 


Return Value 


None. 


FNSTRIP 
2222222999999 922299999999 99292999999999999 
9999 9999999999999 9999999999999 

9 Summary 

fnstrip(str <filename>, int <specifier>, str <target>); 

9 Description 


The fnstrip function allows specific parts of a filename to be ex- 
tracted. In the MS-DOS operating system, a filename can consist of up 
to four parts, the drive, the path, the name, and the extension (e.g., 
C:\TELIX\TELIX.FON). fnstrip processes the filename specified in 
<filename>, and depending on the value of <specifier>, places any com- 
bination of these four parts in the <target> string. Legal values for 
<specifier> and their results are as follows: 


<specifier> Filename portion copied 


Full file name 

All except the drive 

Drive, name, and extension 
Name and extension 

Drive, path, and name (no extension) 
Path and name (no extension) 
Drive and name (no extension) 
Name only (no extension) 

12 Drive and path only 

13 Path only 

14 Drive only 


d On Qn E GM MA G 


Return Value 
None. 


See Also 


filefind 
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€ Example 

str filename[64], shortname[16]; 

gets(filename, 64); // ask for a filename 
fnstrip(filename, 3, shortname); // keep only name & extension 
FOPEN 


2222222229999 
2922292292292 99999999999 999999 

$ Summary 

fopen(str <name>, str <mode>); 

® Description 

The fopen function is used to open a disk file for reading and/or 


writing. The file to be opened is given by <name>. <mode> is a string 
indicating for what use the file should be opened. Legal values for 


mode are: 

vpn Opens for reading 

"w" Opens for writing (truncates any existing file with the 
same name) 

"a" Opens for appending (writing at the end of the file). 
Creates the file if it doesn't exist. 

"y+" Opens for reading and writing. Initial position at the 
beginning of the file (the file must already exist). 

"w+" Opens for reading and writing. If the file exists its 
contents are destroyed. 

"a+" Opens for reading and appending. Creates the file if it 


doesn't exist. 


If a file is opened for both reading and writing (when "r+", "wt", or 
"a+" are used as the mode), an fseek operation is necessary before 
switching from one to the other. 


© Return Value 


The fopen function returns a 'handle' which is an integer number by 
which this file is to be referred to until it is finally closed. A 
value of 0 is returned if the file can not be opened (because it 
doesn't exist, because a disk error occurred, or because there are no 
more file handles available). Only up to 8 files may be opened at a 
time. It is therefore very important to close open files if they are 
no longer needed and when a script is done, or else all available file 
handles will become used up. 


€ See Also 
fclose 
% Example 
int f; 


f = fopen("data.txt", "r"); // open the file for reading 
if (f == 0) 
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prints("Error opening file!"); 


FPUTC 
niii 

$ Summary 

fputc(int <c>, int <fh>); 

® Description 


The fputc function writes a character to the file indicated by the 
file handle <fh>. <c> is the character to write. 


Return Value 


The character written is returned, unless there is an error, in which 
case a value of -1 is returned. 


€ See Also 


fputs, fgetc 


€ Example 

int f, i; 

str teststr[] = "This is a test string"; 

f = fopen("test.dat", "w"); 

for (i = 0; i < 21; ++i) // write out string to file 
fputc(subchr(teststr, i), f); // character by character 
FPUTS 


999999999 99999999999 999999999999 99999999 
9999999 9999999999999 99999999 9OO 

€ Summary 

fputs(str <s>, int <fh>); 

% Description 

The fputs function writes a string to the file represented by file 

handle <fh>. The string must be 512 bytes in length or less (all 

strings end in a zero (0) value, the use of which is usually trans- 


parent; characters are written until this © is encountered. The ® is 
not written). 


Return Value 


A O value is returned if the write is successful, a non-zero value if 
it is not. 


See Also 


fputc, fgets 
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@ Example 

int f, i; 

f = fopen("test.dat", "w"); 

for (i = 0; i < 100; ++i) // write out "Hello" and a new- 
fputs("HelloAMAJ", f); // line one hundred times 

FREAD 


OCE d d d d d d dh dh dh dh dh: dh: dh: dh: dh dh dh dh dh dh dh dh d dh d 
99999 d d d da d da dh: dh: dh: dh: dh: dh: dh dh: da d da da da da Aa da da A A 

€ Summary 

fread(str <buf>, int <count>, int <fh>); 

% Description 

The fread function reads up to <count> bytes from the file represented 

by file handle <fh>. Characters are written to the <buf> variable, 

which must be large enough. 


© Return Value 


The number of bytes actually read is returned, which may be less than 
<count> if an error occurs or and end-of-file is encountered. 


The ferror and feof functions should be used to distinguish an error 
from an end-of-file condition. 


€ See Also 
fwrite 
€ Example 
int f; 


str buffer[40]; 
f = fopen("test.dat", "r"); 


fseek(f, 1000, ®); // goto offset 1000 in file 
fread(buffer, 40, f); // and read 40 bytes of data 
FRENAME 


999999999999 9999999999999 99999999999 d da da d 
99999999 d d da d d da da d: d da da d d da da: d: da da d da da À 
% Summary 
frename(str <oldname>, str <newname>); 
% Description 
The frename function is used to rename a disk file. <oldname> is the 
original name of the file, while <newname> is what it should be re- 


named to. A full drive and path may be included in the original name, 
but should not be placed before the new name. The renamed file will 


stay in the original drive and directory. Case is not significant. 
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Return Value 


If successful, frename returns a © value, otherwise a non-zero value 
is returned. 


See Also 
fdelete 
€ Example 


frename("\TELIX\TELIX.CAP", "OLDTLX.CAP"); 


FSEEK 
OCE d d d d d da da dh dh dh: dh: dh: dh: dh: dh dh dh dh dh dh dh dh d dh dh dh 9 
999 d d d d d da dh da dh dh: dh: dh: dh: dh: da da da d da da da da da da da A A 
€ Summary 
fseek(int <fh>, int <offset>, int <origin>); 
% Description 
The fseek function sets the position of the file pointer in the file 
represented by the file handle <fh>. The file position is where the 
next read or write will take place. <offset> is the signed offset from 
the location specified by <origin>. Legal values for <origin> are: 
0: Beginning of file. 
1: Current position. 
Za End of file. 
The pointer can be positioned anywhere in the file, and even past the 
end of the file (which will extend it). It is illegal to try to posi- 
tion the pointer before the beginning of the file however. 


€ Return Value 


If successful, fseek returns a O value, otherwise a non-zero value is 
returned. 


€ See Also 


ftell 

€ Example 

int f; 

f = fopen("test.dat", "r"); 

fseek(f, 0, 0); // go to offset © in file 
fseek(f, 1000, 0); // go to offset 1000 in file 
fseek(f, -5, 1); // go back 5 places in file 


fseek(f, 0, 2); // go to the end of the file 


Telix v3.22 - SALT Programming Built-in Functions 50 


FTELL 
9999999 9999999999999 99999999 999999999999 
99999 9999999999 9999999999999 9OO 
€ Summary 
ftell(int <fh>); 
% Description 
The ftell function returns the current file position in the file rep- 
resented by file handle <fh>. This is generally the position where the 
next read or write operation will take place. Note however that for a 
file opened in Append mode, the value returned will not necessarily 
return the position of the next write, since Append mode will force 
writes to the end of file regardless of the current file position. 


€ Return Value 


An integer value as described above. A -1 value is returned if an er- 
ror occurs. 


€ See Also 


fseek 


FWRITE 
1332732733723773273377 2777777220000 2455 
© Summary 
fwrite(str <buf>, int <count>, int <fh>); 
® Description 


The fwrite function writes bytes to the file represented by the file 
handle <fh>. <count> number of bytes are written from <buf>. 


€ Return Value 


The number of bytes actually written are returned, which may be less 
than <count> if an error occurred. 


€ See Also 

fread 

€ Example 

int f; 

str buffer[] = "1234567890123456789012345"; 


f = fopen("test.dat", "w"); 
fwrite(buffer, 25, f); // write test pattern to file 
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GET_BAUD 
2222222229999 
2222292222999 9929929999999 999999 

€ Summary 

get_baud(); 

% Description 

The get_baud function returns an integer value which is the current 

baud rate in use on the current communications port (300 through 

115200). 

€ Return Value 

As described above. 

€ See Also 

get_parity, get_datab, get_stopb, get_port 

€ Example 

prints("The current baud rate is "); 

printn(get_baud()); 

prints(""); 

GET_DATAB 
9999999 9999999999999 999999999999 9 
9999999999999 9999999999999 999OO 

€ Summary 

get_datab(); 

% Description 


The get_datab function returns the data bits setting in use on the 
current communications port (7 or 8). 


€ Return Value 
As described above. 
€ See Also 


get_baud, get_parity, get_stopb, get_port 


GETENV 
9999999999999 999999 999999999999 9H9O 
9999999999999 999999 99999999999 


€ Summary 


getenv(str <varname>, str <target>); 
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% Description 


The getenv function may be used to access the DOS Environment and get 
the value assigned to an Environment Variable. <varname> is the name 
of the environment variable to be searched for, and <target> is the 
string variable where whatever is assigned to the environment variable 
should be placed. 


Return Value 

A non-zero (TRUE) value is returned if the function is successful, 
otherwise a zero (FALSE) values is returned (if the environment vari- 
able didn't exist); 


€ Example 


// Get and print whatever is assigned to the TELIX env. variable 
str value[64]; 


if (getenv("TELIX", value)) // if env. variable exists 
prints(value); // print value 
GET_PARITY 


29229999992 92999999999 9 9 999999999 999999 
29229999992 99999999999 999999999 

% Summary 

get_parity(); 


% Description 


The get_parity function returns an integer value which represents the 
current parity setting in use on the current comm port. 


© Return Value 

Returned values are as follows: 
0 No parity 
1 Even parity 
2 Odd parity 

€ See Also 


get_baud, get_datab, get_stopb, get_port 


GET_PORT 
999999 999999999999 9999999999999 999999999 
999999 9999999999999 99999999999 

% Summary 


get_port(); 
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% Description 


The get_port function returns the number (1 through 8) of the current 
communications port being used. 


€ Return Value 

As described above. 

€ See Also 

get_baud, get_datab, get_parity, get_stopb 

€ Example 

prints("Currently using COM"); 

printn(get_port()); 

prints(""); 

GET_STOPB 
9999999 9999999999999 999999999999 99999999 
999999999 9999999999999 99999999 

% Summary 

get_stopb(); 

% Description 


The get_stopb function returns the stop bits setting in use on the 
current com port (1 or 2). 


Return Value 
As described above. 
See Also 


get_baud, get_datab, get_parity, get_port 


GETS 
9999999 999999999 999999999999 999999999999 
999999999 9GH 999999999 9999999999 

% Summary 

gets(str <buffer>, int <max>); 

% Description 

The gets function allows the user to enter a complete string, and use 

the arrow keys to edit it while it is being entered. <buffer> is the 

string variable where the string should be put, while <max> is the 


maximum number of characters the user may enter (from 0 to 80). The 
user may edit the string as it is being entered, with the Left-Arrow, 


Right-Arrow, Ctrl-Left-Arrow, and Ctrl-Right-Arrow keys as it is being 
entered, and insert mode may be toggled on/off with the INS key. 
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String entry is over when the user presses Enter (Carriage Return on 
some computers). The user may press Esc to abort string entry, in 
which case the resulting string will have a length of ©. 


© Return Value 


The number of characters entered by the user are returned. If the user 
pressed Esc to abort string entry, a value of -1 is returned. 


See Also 

getsxy 

€ Example 

int n; 

str password[8]; 
printsc("Enter a password? "); 


n = gets(password, 8); 


GETSXY 


9999999999999 999999999999 999999999999 999 
9999999999999 999999 99999999999 


% Summary 
getsxy(str <targets>, int <max>, int <x>, int <y>, int <color>); 


% Description 


The getsxy function is similar to the gets function, but the x,y lo- 
cation of string entry may be specified, as well as a color attribute. 
<buffer> is the string variable where the string should be put, while 
<max> is the maximum number of characters the user may enter (from 0 
to 80). The cursor will be moved to <x>,<y>, and text entered will use 
a color as described by <color>. 


The user may edit the string as it is being entered, with the Left-Ar- 
row, Right-Arrow, Ctrl-Left-Arrow, and Ctrl-Right-Arrow keys as it is 
being entered, and insert mode may be toggled on/off with the INS key. 
String entry is over when the user presses Enter (Carriage Return on 
some computers). The user may press Esc to abort string entry, in 
which case the resulting string will have a length of ©. 


€ Return Value 


The number of characters entered by the user are returned. If the user 
pressed Esc to abort string entry, a value of -1 is returned. 


€ See Also 
gets 

€ Example 
int n; 


str filename[64] = "C:\TELIX\TELIX.EXE"; 
// allow use to enter filename in black on white 
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// at current cursor position 

n = getsxy(filename, 64, getx(), gety(), 112); 

GETX, GETY 
SSSESSESSSSESSESSSSSS SSS S33 53 ÓN! 

% Summary 

getx(); 

gety(); 

% Description 


The getx function returns the current column (horizontal x axis) po- 
sition of the cursor on the screen. 


The gety function returns the current row (vertical y axis) position 
of the cursor on the screen. 


€ Return Value 


Returned values will range from 0 for the leftmost column to 79 for 
the rightmost column, for the getx function. 


Returned values range from 0 for the upper edge of the screen to 24 
for the lower edge, for the gety functions.. 


€ See Also 


gotoxy 


GOTOXY 
9999 999999999999 9999999999999 99999999999 
999999999999 999999 999999999999 
€ Summary 
gotoxy(int <xpos>, int <ypos>); 
% Description 
The gotoxy function positions the cursor at the screen coordinates 
given by <xpos> and <ypos>. Note that 0,0 is the upper left corner. On 
a 80x25 text screen, the lower right corner would be 79,24. 
% Return Value 
None. 


€ See Also 


getx, gety 


Telix v3.22 - SALT Programming Built-in Functions 56 


€ Example 

gotoxy(0, 0); // go to the top left corner 
gotoxy(79, 24); // go to the bottom right corner 
HANGUP 


2222222299999 
2922292292292 99999999 999999999 

@ Summary 

hangup(); 

% Description 

The hangup function tries to hang-up the modem, exactly as if the user 

had pressed Alt-H while in terminal mode. This is accomplished by 

first dropping (turning off) a signal called the DTR line, and if that 

is unsuccessful, sending the hang-up string defined in the configu- 

ration menu. 

Return Value 

A non-zero (TRUE) value is returned if the hang-up is successful, 

otherwise a zero (FALSE) value is returned. 

HELPSCREEN 
9999999 9999999999999 9999999999 d 
999 999999999999 9999999999999 00 

€ Summary 

helpscreen(); 


% Description 


The helpscreen function displays the help/status screen, as if the 
user had pressed the appropriate key while in terminal mode. 


Return Value 


None. 


INKEY, INKEYW 
2292299999999 9999999999 999999999999 99999 
2292299999999 9999999 9999999999 

% Summary 


inkey(); 


inkeyw(); 
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% Description 


The inkey function returns a character from the keyboard, but does not 
wait for a key to be pressed. 


The inkeyw function returns a character from the keyboard, and waits 
for a key to be pressed if the keyboard buffer is empty. 


Note that Telix while executing a script file checks the keyboard be- 
tween every command to see if the user wants to abort the script. For 
these commands to work, this keyboard checking must be disabled. This 
is done by setting the _scr_chk_key system variable to a non-zero 
(FALSE) value (that variable is further described in the section on 
system variables). 

© Return Value 


inkey returns the first character in the keyboard buffer, or a value 
of 0 if the keyboard buffer is empty. 


inkeyw waits until a key has been pressed if none is available in the 
keyboard buffer, and returns that value. 


Both of these functions also return extended key code values which are 
not part of the ASCII character set (for example, the code for Alt-D). 
These values are described in the Appendix. 


€ Example 


chr = inkey(); 


INSCHRS 
9999999 9999999999999 999999999999 99999999 
999 999999999999 9999999999999 A A 
% Summary 
inschrs(str <source>, str <target>, int <pos>, int <num>); 
% Description 
The inschrs function is used to insert characters from one string into 
another at a specific position, shifting existing characters to the 
right. Characters are taken from <source> and placed in <target>, at 
an offset indicated by <pos>. Note that string offsets are numbered 
starting at 0, so the first character would have an offset of 0, the 
second 1, etc. Only <num> characters are inserted, and existing char- 
acters are shifted to the right (and are lost if they shift past the 
space allocated for the string). 
€ Return Value 
None. 


€ See Also 


copystr, copychrs 
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€ Example 
str test[24] = "Good-bye"; 


// add "Hello" to the front of the existing string 
inschrs("Hello ", test, 0, 6); 


ISALNUM - ISUPPER 


9999999999999 999999999 999999999999 999999 
9999999 9GH O99 999999999 GH 99999 9OO9 


€ Summary 

isalnum(int <c>); Test for alphanumeric ('A'-'Z', 'a'-'z', or '0'- 
TO" 

isalpha(int <c>); Test for letter ('A'-'Z' or 'a'-'z') 


isascii(int <c>); Test for ASCII value (0-255) 
isentrl(int <c>); Test for Control character (0-31 or 127) 
isdigit(int <c>); Test for digit ('0'-'9') 
islower (int <c>); Test for lower case ('a'-'z') 
isupper (int <c>); Test for upper case ('A'-'Z') 
% Description 
The functions listed above test an integer value and return a non-zero 
(TRUE) value if the test condition is satisfied, or a zero (FALSE) if 
it is not. 
Except for isascii, these functions give valid results only for in- 
teger values in the ASCII character set, that is, values for which 
isascii is true. 
© Return Value 
A non-zero (TRUE) value is returned if the test condition is sat- 
isfied, a 0 (FALSE) value otherwise. 
IS_LOADED 
99999999999 99999999999 999999999999 999999 
9 9 999999999 9999999999999 
€ Summary 
is_loaded(str <filename>) ; 
% Description 
The is_loaded function is used to determine if a SALT script, in- 


dicated by <filename> is currently loaded into memory. The script can 
be in memory if it was explicitly loaded with the load_script func- 


tion, or is still in memory because it previously was run and did not 
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finish executing. If filename does not include an extension, ".SLC" is 
automatically added. 


Return Value 


A non-zero (TRUE) values is returned if the indicated script file is 
in memory, otherwise a zero (FALSE) value is returned. 


See Also 

load_scr, unload_scr 

@ Example 

if (!is_loaded("TESTSCR")) // make sure script is in memory 


load_scr("TESTSCR"); 


ITOS 
99999999 99999999999 9999999999 99999999999 
999999999999 9999999999 99999999 

% Summary 

itos(int <value>, str <s>); 


% Description 


The itos function writes out the digits of the supplied integer value 
to <s>. 


Return Value 

None. 

See Also 

stoi 

@ Example 

int chr; 

str s[16]; 

chr = inkeyw(); // get a user keystroke 


itos(chr, s); // and print out ASCII value of character 
prints(s); 


KEYGET 
2292299299999 9999999999999 999 99999999999 
2299229999999 9999999 9999999999 

% Summary 


keyget(int <key>, int <table>, str <buffer>); 
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% Description 

The keyget function is used to look at what text is assigned to a key. 
<key> is an integer value representing the key (as described in the 
appendix). Any macro text assigned to this key will be placed in 
<buffer>. Telix keeps two key macro definition tables in memory at all 
times, a user key table, and a terminal key table, loaded in whenever 
the current terminal is changed. If <table> is 0, the key is assumed 
to be in the user table. If <table> is 1, the key is assumed to be in 
the terminal table. 

Return Value 

None. 

See Also 

keyset, keyload, keysave 

€ Example 

str s[100]; 

prints("Text currently assigned to the F1 key in user table is:"); 


keyget(@x3b00, 0, s); 
prints(s); 


KEYLOAD 
99999999999 99999999999 999999999999 d 
9999999 9999999999999 99999999 A A 
% Summary 
keyload(str <fname>, int <table>); 
% Description 
The keyload function is used to load a keyboard macro definition file 
into Telix. <fname> is the name of the definition file (if no exten- 
sion is given, .KEY is assumed). Telix always keeps two definition ta- 
bles in memory, a relatively constant user table, and a terminal table 
which changes with each different terminal and holds the proper key 
assignments for that terminal. If <table> is 0, then the definitions 
are loaded into the user table. If <table> is 1, the definitions are 
loaded into the terminal table. 
€ Return Value 


A value of -1 is returned if there are problems loading the key file, 
otherwise a non-zero (TRUE) value is returned. 


€ See Also 
keysave, keyget, keyset 
% Example 


key load( "SPECIAL", 0); 
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KEYSAVE 
9999999 9999999999999 999999999999 99999999 
999 999999999999 9999999999999 9OO 
€ Summary 
keysave(str <fname>, int <table>); 
% Description 
The keysave function is used to save the current macro key text def- 
initions to a disk file. <fname> is the file to save the definitions 
to, and if no extension is given, ".KEY" is added. Telix always keeps 
two key definition tables in memory, a relatively constant user table, 
and a terminal table which changes with each different terminal and 
holds the proper key assignments for that terminal. If <table> is 0, 
then the definitions from the user table are saved. If <table> is 1, 
the definitions from the terminal table are saved. 
© Return Value 


A value of -1 is returned if there is a problem writing to the file, 
otherwise a non-zero (TRUE) value is returned. 


€ See Also 


keyload, keyget, keyset 


KEYSET 
9999999 9999999999999 999999999999 99999999 
999999999 99999999999 99999999 A A 
€ Summary 
keyset(int <key>, int <table>, str <text>); 
% Description 
The keyset function is used to assign text to a key. <key> is an in- 
teger value representing the key (as described in the appendix). 
<text> is what to assign to this key. Telix always keeps two key defi- 
nition tables in memory, a relatively constant user table, and a ter- 
minal table which changes with each different terminal and holds the 
proper key assignments for that terminal. If <table> is 0, the key 
definition in the user table is affected. If <table> is 1, the key 
definition in the terminal table is affected. 
€ Return Value 
None. 


€ See Also 


keyget, keyload, keysave 
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% Example 
// Assign a name to the F1 key in the user table 
// Note that if the terminal table also holds a 


// definition for that key it will take precedence 
keyset((0x3b00, 0, "Joe Smith"); 


LOADFON 
9999999 9999999999999 99999999 999999999999 
99999 9999999999 9999999999999 00 
€ Summary 
int loadfon(str <filename>) ; 
% Description 
The loadfon function loads the given dialing directory file. The com- 
plete name must be given, including any extension (e.g. .FON) or the 
disk drive/directory if the file is not in the current directory. 
€ Return Value 
A non-zero (TRUE) value is returned if the dialing directory file is 


successfully loaded. If some sort of error occurs (file does not ex- 
ist, file reading error, etc.) a zero (FALSE) value is returned. 


LOAD_SCR 
9999999 9999999999999 9999999999 9999999999 
999 999999999999 9999999999999 00 
€ Summary 
load_scr(str <filename>); 
% Description 
When a script is run (either by the user manually running it from ter- 
minal mode, or from within another script), it is usually loaded from 
disk. The load_scr function is used to load a script into memory ahead 
of time, providing a savings in time when the script must be run re- 
peatedly. <filename> is the name of the script file to load, and if no 
extension is given, ".SLC" is assumed. 
Return Value 
If there is a problem loading the script file (it is not there or 
there is not enough memory),a value of -1 is returned. Otherwise a 
non-zero (TRUE) value is returned. 
€ See Also 


unload_scr, is_loaded 


€ Example 


int stat; 
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stat = load_scr("TEST"); // load TEST.SLC 


NEWDIR 
2222222299999 
2222222999999 2929999999999 

€ Summary 

newdir(str <directory>); 

% Description 

The newdir function is used to change the current drive and/or di- 

rectory. The <directory> argument should be the drive and/or directory 

to change to. 

Return Value 

A non-zero (TRUE) value is returned if the function is successful, 

otherwise a zero (FALSE) values is returned (if the drive or directory 

is illegal or doesn't exist). 

See Also 

dos, run 


€ Example 


newdir("C:\TELIX"); 


PRINTC 


922222299992 2222999992929 9999999999999 
99999999 9999999999999 999999999 

€ Summary 

printc(int <chr>); 


% Description 


The printc function prints the character represented by the ASCII 
value <chr> to the terminal screen. 


© Return Value 

<chr> is returned. 

€ See Also 

prints, printsc, printn 
€ Example 


printc('A'); 


printc(7); // print ASCII value 7 (BELL sound) 
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printc(keyinw()); // print user keypress 


PRINTER 
2222222299999 
2222222999999 9292999999999 9999 

€ Summary 

printer(int <state>); 

% Description 

The printer function is used within a script file to turn the printer 

on or off, as if the user had pressed the appropriate key in terminal 

mode. If <state> is a non-zero (TRUE) value, echoing to the printer is 
turned on, otherwise echoing is turned off 

© Return Value 

None. 

€ See Also 

capture 


€ Example 


printer(1); // turn on printer log 


PRINTN 
23322322223283323232233232237 200128525 

€ Summary 

printn(int <num>); 

% Description 


The printn function prints the passed integer number to the terminal 
screen. The cursor is NOT advanced to the beginning of the next line. 


Return Value 

The value of the passed integer is returned. 
€ See Also 

prints, printsc, printc 

€ Example 


printsc("Current baud rate is "); 
printn(get_baud); 
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PRINTS, PRINTSC, PRINTSC_TRM 


99999 99999999999 999999999999 9H9 9 
9999999999999 999999 99999999999 


€ Summary 

prints(str <outstr>); 
printsc(str <outstr>); 
printsc_trm(str <outstr>); 


% Description 


The prints function prints the passed string at the current cursor po- 
sition on the screen, followed by a Carriage Return and Line Feed 


(which places the cursor at 
The printsc function prints 
position on the screen. The 
hence the 'c', which stands 


The printsc_trm function is 


the beginning of the next line). 

the passed string at the current cursor 
cursor is not advanced to the next line, 
for continuous. 


similar to the above, except that out- 


putted characters pass through the current terminal emulator, so ter- 
minal escape sequences may be included in output strings. 


© Return Value 

None. 

€ See Also 

printn, printc 

€ Example 
prints("Hello"); 
printsc("HelloAMAJ"); // 


printsc_trm("A[L[H"); // 


PSTRA, PSTRAXY 


same effect as above 


go to top left corner in VT102 emulation 


9222229299299 
$9 9 9999 999999999999 9999 


9990990090 


€ Summary 


pstra(str <s>, int <color>); 


pstraxy(str <s>, int <x>, int <y>, int <color>); 


% Description 


The pstra (Print STRing with color Attribute) function is used to 
print a string to the screen, similar to the prints/printsc functions. 


This function is much faster however, and should be used when speed is 
important. As well, it allows a color to be specified for the text. 
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<s> will be printed to the screen at the current cursor position using 
a color as specified by <color>. 


The pstraxy function is similar to the above, but allows you to spec- 
ify where to print the string. The string is printed at <x>,<y>, with 
0,0 being the upper left corner of the screen. 

Note that prints goes through a basic TTY type terminal emulator, so 
strings printed using it may contain the basic cursor control code, 
while pstra writes directly to the screen, ignoring these sequences. 
€ Return Value 

None. 

€ See Also 

prints, printsc 


€ Example 


pstraxy("Enter name:", 10, 10, 112); // print in inverse text 


RECEIVE 
999999999 99999999999 999999999999 99999999 
999 999999999999 9999999999999 9OO 

€ Summary 

receive(int <protocol>, str <name>); 

% Description 

The receive function is used to receive (download) one or more files 

from another system. <protocol> is the letter used to select the ap- 


propriate protocol from the actual download menu in Telix (e.g., 'X' 
for Xmodem), as follows: 


LA! ASCII 

'K' Kermit 
'M' Modem? 
LS? SEALink 
ET" Telink 
'x' Xmodem 
vad? Xmodem-1k 
'G' Xmodem-1k-g 
Y! Ymodem 
E" YmodEm-g 
'Z' Zmodem 


If an external protocol is defined, <protocol> may also be the key 
used to select it. <name> is the name the file should take. For pro- 
tocols which pass the name, such as SEAlink, Zmodem, Ymodem (batch), 
and others, the name field should be an empty string, "". If a down- 
load directory has been defined in the Configuration Menu, received 
files will go there, unless the <name> string explicitly includes a 
path to another drive/directory. 
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Return Value 


A value of -1 is returned if the transfer was aborted, except if the 
Carrier (connection) was lost, in which case a value of -2 is re- 
turned. 


€ See Also 
send, _down_dir 
€ Example 

int result; 


result = receive('X', "TEST.EXE"); 
if (result < ®) 
prints("File transfer failed!"); 


REDIAL 
2222229999222 9999922929999 999999999999 
2922222299992 2992999999999 999999 

€ Summary 

redial(str <dialstr>, int <maxtries>, int <no_link>); 


% Description 


The redial function dials the entries specified in <dialstr>. The en- 
tries should be entered in the same format as used when typing entries 
in the dialing directory. If <dialstr> is empty (""), the redial queue 
is presented to the user, as if Alt-Q was pressed while in terminal 
mode. <maxtries> is the maximum number of dialing attempts. For exam- 
ple, if the string contains one entry, and <maxtries> is equal to 5, 
Telix will attempt to dial the number 5 times. If five entries are in- 
dicated, and <maxtries> is equal to 5, each number will only be at- 
tempted once. If <maxtries> is 0, dialing will continue until a con- 
nection is established. If an entry is connected to, and has a linked 
script file attached, that script will be run, unless <no_link> is 
non-zero (TRUE). 


© Return Value 


If there was a connection, the redial function returns the entry num- 
ber of the of the entry which was connected to (or 1 if a manual num- 
ber was dialed). If there was no connection established, 0 is re- 
turned. If the <dialstr> has a bad format, -1 is returned. 


Also, when a connection is successfully established, the entry number 
of the entry connected to is placed in the system variable 
_entry_enum, while the name of the entry connected to is placed in the 
system variable _entry_name. 


€ See Also 


dial 
_entry_enum, _entry_name 
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@ Example 


int stat; 

str number_list[] = "1 4 27"; 
redial("10 15", 0); 
redial("m967-1111", 5); 

stat = redial(number_list, 0); 


RUN 


9999999999999 999999 999999999 99999999999 
99999 99999999999 9999999999999 


% Summary 
run(str <filename>, str <comline>, int <mode>); 
% Description 


The run function executes the indicated file. The indicated file must 
either be in the current directory, be on the DOS PATH, or must in- 
clude the full path to the file (i.e., specify the drive and/or direc- 
tory). Make sure that if you run a program that expects user input you 
are on hand to give it. The <comline> parameter is the command line 
which should be passed to the called program. The <mode> argument 
specifies several options, as follows: 


0 Original screen is restored when program is completed. 

1 When program is completed, the user is prompted to press a 
key and screen is restored as soon as it is pressed. 

2 Original screen is not restored when program is completed 


This function is similar to the dos function. Because it uses less 
memory and loads faster, it is preferable to that function unless a 
DOS Batch file has to be run, or an internal DOS command must be spec- 
ified, in which case the dos function has to be used. 

€ Return Value 

The run function returns a -1 if the file can not be run (because it 
can not be found or there is not enough memory). Any other value is 
the value returned by the called program (usually 0), but a positive 
value may also result when the called program is aborted. 

€ See Also 

dos, dosfunction 

€ Example 


run("CS", "test", 1); 


$9 9 
$9 9 


$9 9 
$9 9 


Telix v3.22 - SALT Programming Built-in Functions 69 


SCROLL 


Y99099990990909909099090990909909099090990990090900900000 
9999999999999 999999 99O 


9299999 
€ Summary 


scroll(int <x>, int <y>, int <x2>, int <y2>, int <lines>, int 
<color>); 


% Description 

The scroll function is used to scroll or clear a region of the screen. 
The area to handle is defined by <x>,<y> as the upper left corner, and 
<x2>,<y2> as the lower right corner (the upper left corner of the 
screen is 0,0). If the <lines> parameter is a positive value, text 
within the region is scrolled up that many lines. If <lines> is a neg- 
ative value, text within the region is scrolled down that many lines. 
If <lines> is equal to 0, the entire region is cleared. Empty lines 
scrolled into the region will have a color of <color>. 

© Return Value 

None. 

See Also 

box 


€ Example 


scroll(0, ©, 79, 24, 10, 7); // scroll screen up 10 lines 


SEND 


9999999999999 999999999999 9999999999999 
9999999999999 999999999 


999999 

€ Summary 

send(int <protocol>, str <name>); 

% Description 

The send function is used to send (upload) one or more files to an- 
other system over the comm port. <protocol> is the letter used to se- 


lect the appropriate protocol from the actual download menu in Telix 
(e.g., 'X' for Xmodem) as follows: 
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LA! ASCII 

'K' Kermit 
'M' Modem? 
"Ss! SEALink 
'T! Telink 
'x' Xmodem 
le Xmodem-1k 
'G' Xmodem-1k-g 
Y! Ymodem 
'E' YmodEm-g 
NZ: Zmodem 


If an external protocol is defined, <protocol> may also be the key 
used to select. <name> is the file(s) to send. <name> may include the 
DOS wildcard characters * and ?, in which case all matching files will 
be sent (however the protocol used must be capable of sending more 
than one file at a time, e.g., SEAlink, Zmodem, Ymodem (batch), etc.). 
If an upload directory has been defined in the Configuration Menu, 
Telix will look there for files specified to be sent, unless the 
<name> string explicitly includes a path to another drive/directory. 
© Return Value 

A value of -1 is returned if the transfer was aborted, except if the 
carrier (connection) was lost, in which case a value of -2 is re- 
turned. 

€ See Also 


receive, _up_dir 


SEND_BRK 
9999999 9999999999999 9999999999 9999999999 
99999 9999999999999 9999999999 A A 

% Summary 

send_brk(int <duration>); 

% Description 

The send_brk function sends a sustained break signal over the modem 

port, for a period of time, specified in tenths of a second, by 

<duration>. 


€ Return Value 


None. 


SET_CPARAMS 
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% Summary 


set_cparams(int <baud>, int <parity>, int <data>, int <stop>); 
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% Description 

The set_cparams function is used to set the communications parameters 
in use on the current communications port. Allowable <baud> values are 
300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200. <parity> 
is an integer number which stands for the parity to use. Allowable 
values are 0, 1, and 2, which stand for None, Even, and Odd parity, 
respectively. <data> is the data bits setting to use; allowable values 
are 7 or 8. <stop> is the stop bits setting to use; allowable values 
are 1 or 2. Note that some combinations of settings are illegal. 

€ Return Value 


If all the settings are legal values, a non-zero (TRUE) value is re- 
turned, otherwise a value of -1 is returned. 


€ See Also 
set_port 
€ Example 
set_cparams(2400, 0, 8, 1); 
set_cparams(9600, get_parity(), get_datab(), get_stopb()); 
SET_DEFPROT 
9999999 9999999999999 9999999999 9999999999 
99999 9999999999999 999999999999 
% Summary 
set_defprot(int <protocol>); 
% Description 
The set_defprot function is used to set the default file transfer pro- 
tocol presented to the user when a file transfer is requested. 
<protocol> is the letter used to select the appropriate protocol at 
the file transfer menu (see the description of the receive function 
for possible options). 
Return Value 
None. 
See Also 
receive, send 


€ Example 


set_defprot('Z'); // Select Zmodem as default protocol 
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SETCHR 
ssssssessesssssseesssssssseesse IN! 

$ Summary 

setchr(str <buf>, int <pos>, int <c>); 

® Description 


The setchr function puts the character <c> at position <pos> in the 
string indicated by <buf>. 


© Return Value 

The character <c> is returned. 
€ See Also 

setchrs, subchr 

€ Example 

int i; 

str s[100]; 


for (i = 0; i < 10; ++i) // set first 10 characters to 'A' 
setchr(s, i, 'A'); 


SETCHRS 
999 999999999999 9999999999999 999999999999 
999999 9999999999999 99999999999 

€ Summary 


setchrs(str <buf>, int <pos>, int <c>, int <count>); 

% Description 

The setchrs function is used to set a range of characters in a string 
to the same value. <buf> is the string in which characters will be 
set, starting at an offset indicated by <pos> (note that the first 
character in a SALT string has an offset of 0, the second, 1, and so 
on). <count> characters will be set to the value of <c>. 

€ Return Value 

None. 

€ See Also 

setchr, subchrs 


€ Example 


str s[100]; 
// zero out an entire string 


setchrs(s, 0, 0, strmaxlen(s)); 
// set the first ten characters to 'A' 
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setchrs(s, 0, 'A', 10); 


SET_PORT 
122222282323222222232222222222 ÓN 
© Summary 
set_port(int <port>); 
© Description 


The set_port function is used to select a communications port to use. 
Allowable values for <port> are 1 through 8. 


© Return Value 


If the new port can be successfully initialized, a non-zero (TRUE) 
value is returned, otherwise a value of -1 is returned. 


€ See Also 


set_cparams 


SET_TERMINAL 
iinan 

$ Summary 

set_terminal(str <terminal_name>); 

® Description 


The set_terminal function is used to switch the current terminal being 
emulated. <terminal_name> is the name of the new terminal to use, as 
follows: 


11 TTY 11 
"ANSI-BBS" 
"ANS I 11 
"VT102" 
"VT52" 
"AVATAR" 


€ Return Value 

A value of -1 is returned if there is a problem switching to the in- 
dicated terminal emulator, otherwise a non-zero (TRUE) value is re- 
turned. 


€ Example 


set_terminal("VT102"); 
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SHOW_DIRECTORY 
9999999 9999999999999 99999999 999999999999 
99999 9999999999999 999999999999 
€ Summary 
show_directory(str <filespec>, int <cecho>, int <carrier>); 
% Description 
The show_directory function displays a files directory listing to the 
screen and optionally echoes it to the comm port. The <filespec> is 
the file mask to use (e.g., "*.*"), and may also include a drive 
and/or directory, just like the DOS 'dir' command. If the <cecho> 
argument is non-zero (TRUE), the listing is also be echoed to the comm 
port. If the <carrier> argument is non-zero (TRUE) and the listing is 
being echoed to the comm port, the carrier signal is monitored in case 
the connection is lost (which aborts the display). The user is 
prompted to press a key after every screen full of data. 
© Return Value 
None. 
€ See Also 
dos, dosfunction 


@ Example 


show_directory("*.DOC", 0, 0); 


STATUS_WIND 
9999999 9999999999999 999999999999 d 
999999999 99999999999 99999999 9OO 
% Summary 
status_wind(str <message>, int <duration>); 
% Description 
The status_wind function is used to display a status message, 
<message>, in a pop up window. <duration> is the time in tenths of 
seconds to display the window, after which it is removed, and the pre- 
vious contents of that screen area are restored. 
€ Return Value 
None. 
€ See Also 


box, pstra, pstraxy 


€ Example 


status_wind("File not found!", 10); 
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STOI 
9999999 9999999999999 99999999 999999999999 
9999999 9999999999999 99999999 A A 
€ Summary 
stoi(str <s>); 
% Description 
The stoi function assumes that <s> is a string which contains an in- 
teger number, written out. It processes the string digit by digit and 
returns that value. For example, stoi("123") would return the integer 
value 123. Processing stops at the first non-digit character. If an 
empty or invalid string is parsed, a value of © is returned. 
€ Return Value 
An integer value as described above. 
€ See Also 
itos 
€ Example 
str s[] = "123"; 


if (stoi(s) == 123) 
prints("This will always be printed!"); 


STRCAT 
9999999 9999999999999 999999999999 99999999 
2222222229999 2929999999999 

% Summary 

strcat(str <string1>, str <string2>); 

% Description 

The strcat function concatenates (adds or appends) one string to the 

other. <string2> is added to the end of <stringi>. If <string1> is not 

large enough only as many characters as will fit are added. 

© Return Value 

None. 

€ Example 

str s[80] = "hello"; 

strcat(s, "good-bye"); 


if (s == "hellogoodbye") 
prints("This will always be printed"); 
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STRCHR 
OCE d d d d d d da dh dh dh: dh: dh: dh: dh: dh dh dh dh dh dh dh dh d dh H 
9999999 d d d d dh dh: dh: dh: dh: dh: d da da d da da da da da da A A A 
€ Summary 
strchr(str <s>, int <pos>, int <c); 
% Description 
The strchr function is used to search for a character within a string. 
<s> is the string to search, and <pos> is the starting position of the 
search, and <c> is the character (ASCII value) to search for. If the 
character, its offset is returned, otherwise a value of -1 is re- 
turned. Note that the first character in a string has an offset of 0, 
not 1 as in some languages. 
Return Value 
An integer value as described above. 
@ Example 


// Count how many times a certain char occurs in a string 


int i, count = 0; 


str s[] = "abcabcabcabcabc"; 
i=0; 
do 

{ 

i = strchr(s, i, 'a'); 

if (i != -1) 

count = count + 1; 

T 
while (i != -1); 
STRCMPI 


9999999 9999999999999 999999999999 99999999 
9999999 99999999999 9999999999 A A 

€ Summary 

strempi(str <string1>, str <string2>); 


% Description 


The strcmpi function is used to compare two strings (in a similar man- 
ner to the ==, >, and < operators, but ignoring the case of the 
strings). The strings are compared character by character until a dif- 
ference is found or the end of either string is found, and an integer 
value is returned as follows: 
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0 <string1> is equal to <string2> 
< 0 <string1> is less than <string2> 
> 0 <string1> is greater than <string2> 


© Return Value 

An integer value as described above. 

€ Example 

if (strcmpi("HeLLo", "hEL1lO"); 

prints("This will always be printed"); 

STRLEN 
9999 999999999999 9999999999999 999999999 
99 9999999999999 9999999999999 

€ Summary 

strlen(str <s>); 

% Description 

The strlen function returns the number of characters in the string 
<s>. Since strings are terminated with a © (NULL) character, this 
function really counts the number of characters before a © is en- 
countered. 

€ Return Value 

An integer value representing the length of a string. 

€ See Also 

strmaxlen 

€ Example 

str teststr[] = "This is a test string"; 


printsc("The length of 'teststr' is "); 
printn(strlen(teststr)); 


STRLOWER 
a a 
Summary 

strlower(str <s>); 

® Description 


The strlower function processes the string <s> and changes each upper 


case character to lower case. Other characters are left unchanged. 
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© Return Value 
None. 
€ See Also 


strupper 


STRMAXLEN 


9999999 9999999999999 9999999999 d 
9999999 9999999999999 99999999 00 

€ Summary 

strmaxlen(str <s>); 

% Description 

The strmaxlen function returns the maximum number of characters that 
string <s> can hold. This is the same value as used when the string is 
defined elsewhere in the program (e.g. if the string was defined as 
'str hello[16];', a value of 16 would be returned). All strings are 
really one character larger than defined, as the last character is al- 
ways a terminating O (NULL). However, since this value can not be 
changed, it is not counted as part of the length of a string. 

Return Value 

An integer value as described above. 

€ See Also 


strlen 


STRPOS, STRPOSI 
9999999 9999999999999 9999999999 9999999999 
99999 9999999999 9999999999999 00 
€ Summary 
strpos(str <string1>, str <substr>, int <start>); 
strposi(str <stringi>, str <substr>, int <start>); 
% Description 
The strpos function is used to search for one string within another. 
<string1> is scanned for <substr>, starting at the offset (position) 
indicated by <start>. If the sub-string is found, its offset is re- 
turned, otherwise a value of -1 is returned. Note that the first char- 
acter has an offset of 0, not 1 as in some languages. 


strposi is a case insensitive version of the above. 


€ Return Value 


An integer value as described above. 
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€ Example 


str teststr[] = "cat dog cat dog"; 
int i = 0, num = 0; 


while (1) // loop as long as needed 
i = strpos(teststr, "cat", i); 
if (i == -1) 
break; 
i = i+ 1; // make sure we don't find the same one 
num = num + 1; // increment count 


} 


prints("'cat' was found "); 

printn(num); 

prints(" times."); 

STRUPPER 
OE d d d d d d dh dh dh: dh: dh: dh: dh: dh: dh dh dh dh dh dh dh dh dh dh dh dh dh dh: dh: dh: dh: dh dh dh d d A À 
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€ Summary 

strupper(str <s>); 


% Description 


The strupper function processes the string <s> and changes each lower 
case character to upper case. Other characters are left unchanged. 


© Return Value 
None. 
See Also 


strlower 


SUBCHR 
323203232232242232322322 E 

€ Summary 

subchr (str <s>, int <pos>); 

% Description 


The subchr function returns the character found at position <pos> in 
string <s>. Note that an integer (representing the ASCII value of the 
character) is returned, not a string. <pos> may be anywhere within the 
string length as defined. Note that positions start from 0. The ist 
character in a string is at position ©, the 40th at position 39, etc. 
A string defined with a length of 10 would have valid positions of 0 


to 9, with position 10 always returning the 0 value that terminates 
all strings. 
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Return Value 

An integer value as described above. 

See Also 

setchr, subchrs 

€ Example 

// This will print out the contents of a test string, extracting 


// each character individually, and stopping when a © is reached 
// which marks the end of all proper strings 


int i; 
str s[] = "This is a test string"; 
for (i = 0; subchr(s, i) != 0; ++i) 


printc(subchr(s, i)); 


SUBCHRS 
9999999 9999999999999 9999999999 9999999999 
999999999 9999999999999 99999999 
€ Summary 
subchrs(str <source>, int <pos>, int <count>, str <target>); 
% Description 
The subchrs function copies a number of characters from one string 
into another, Characters from position <pos> in <source> are copied 
into string <target> (note that SALT string offsets start at 0, not 1 
as in some Languages). <count> characters are copied. Only as many 
characters as will fit in <target> are copied. 
This function is very similar to substr, except that it is not string 
oriented, and does not stop copying characters when a O value is en- 
countered. 
€ Return Value 
None. 


€ See Also 


substr, subchr, copystr, copychrs 


SUBSTR 
999999999 999999999999 9999999999 999999999 
999999 9999999999999 99999999999 

% Summary 


substr(str <source>, int <pos>, int <max>, str <target>); 
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% Description 

The substr function copies a portion of one string to another. Char- 
acters from position <pos> in string <source> are copied until into 
string <target> (note that SALT string offsets start at 0, not 1 as in 
some languages). Characters are copied until a © (NULL) value is en- 
countered (normally at the end of every string), or <max> characters 
are copied. A © (NULL) is always copied at the end of the target 
string. The © does not count as part of the <max>. Only as many char- 
acters as will fit in <target> are copied. 

Return Value 

None. 

See Also 

subchrs, copystr, copychrs 

€ Example 

str s[] = "horse cat dog", s2[16]; 

substr(s, 6, 3, s2); 


if (s2 == "cat") 
prints("This will always be printed"); 


TDAY - TYEAR 
9999999 9999999999999 999999999999 99999999 
99999 9999999999 9999999999999 00 
€ Summary 
tday(int <timeval>); 
thour(int <timeval>); 
tmin(int <timeval>); 
tmonth(int <timeval>); 
tsec(int <timeval>); 
tyear(int <timeval>); 
% Description 
These functions all extract time information from <timeval>, which is 
a date and/or time of day. If <timeval> represents a date, it is the 
number of seconds from Jan 1, 1970 to that date. If <timeval> repre- 
sents a time of day, it is the number of seconds from midnight to that 
time. If it is both, the two above values are simply added together. 
Among others, the curtime and filetime functions return time/date in- 


formation in this format. 


tday returns an integer value from 1 to 31 representing the day por- 
tion of the date stored in <timeval>. 
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thour returns an integer value from 0 to 23 representing the hour por- 
tion of the time stored in <timeval>. 


tmin returns an integer value from © to 59 representing the minutes 
portion of the time stored in <timeval>. 


tmonth returns an integer value from 1 to 12 representing the month 
portion of the date stored in <timeval>. 


tsec returns an integer value from 1 to 59 representing the seconds 
portion of the time stored in <timeval>. 


tyear returns an integer value from 1970 to 2019 representing the year 
portion of the date stored in <timeval>. 


© Return Value 

An integer value as described above. 
€ See Also 

curtime, filetime 

@ Example 

int t; 

t = curtime(); 

printsc("This is month number "); 
printn(tmonth(t)); 

printsc(" in the year "); 


printn(tyear(t)); 
prints("."); 


TERMINAL 
2222222229999 
2222222299999 9992999999999 9999 

% Summary 

terminal(); 

% Description 

The terminal function when called allows Telix to process characters 

coming in from the serial port and print them on the terminal screen, 

and process user keystrokes. If a function has nothing to do (for ex- 
ample while using the track function), it can call terminal to make 
sure characters and user keystrokes are processed. Note that if a user 
script wants to process every incoming character (e.g., with the cgetc 
function, the terminal function should never be called). 


Return Value 


None. 


$9 9 
$9 9 
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€ See Also 
track 
@ Example 


// This will wait forever for either of two strings 
// to come in from the comm port, and then stop. 
int t1, t2, stat; 

t1 = track("hello", 0); 

t2 = track("good-bye", 0); 

while (1) // loop forever 


terminal(); // The call to terminal() lets any characters 
// that come in be looked at by Telix's 
// internal routines for a match with. 
// Incoming chars are also printed on the 
// terminal screen and user keystrokes are 
// handled 
stat = track_hit(0); 
if (stat == t1 || stat == t2) // exit if one of the strings 
break; // came in 
} 


track_free(t1); // stop Telix for looking for more matches 
track_free(t2); 


TIME 


d: d d: d d d: dh d: dh dh dh: dh dh: dh dh: dh: dh: dh dh dh: dh: dh: dh dh dh: dh dh: dh: dh: da: dh da: d d d A A 
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999999 

% Summary 

time(int <timeval>, str <buffer>); 

% Description 

The time function writes out a time in <buffer> in the form hh:mm:ss, 
with hh being the hour in either 12 or 24 hour format based on the 
_time_format). <timeval> is the time, represented as the number of 
seconds since midnight. Time values in this form are returned by the 
curtime and filetime functions, among others. 

Return Value 

None. 

€ See Also 

date, curtime, filetime 

% Example 

str s[16]; 

printsc("The current time is "); 


time(curtime(), s); 
prints(s); 
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TIME_UP - TIMER_TOTAL 


9999999999999 999999999 999999999999 999999 
9999999999999 999999 99999999999 


@ Summary 

time_up(int <thandle>); 

timer_free(int <thandle>); 
timer_restart(int <thandle>, int <time>); 
timer_start(int <time>); 

timer_total(int <thandle>); 

% Description 


The timer functions are used to set and keep track of a timer vari- 
able. 


The timer_start function is used to start a timer. This timer can 
later be used to check if a certain period of time has elapsed from 
when the timer was started. This function returns an integer value 
called a timer handle, that is used to refer to this timer in the fu- 
ture. The <time> parameter is the time from the present (in tenths of 
a second) after which the timer should be considered elapsed (for use 
with the time_up function). If the time_up function will not be used, 
then this parameter can be anything. 


The time_up function returns a non-zero (TRUE) value if the timer rep- 
resented by timer handle <thandle> has elapsed, otherwise a O (FALSE) 
value is returned. The period of time after which a timer will elapse 
is specified in the timer_start function. 


The timer_total function returns the total time (in tenths of a sec- 
ond) since the timer represented by timer handle <thandle> was started 
or restarted. 


The timer_restart function performs the same things as timer_start, 
except that it restarts an existing timer, represented by timer handle 
<thandle>. 


The timer_free function frees a timer variable when it is no longer 
needed. <thandle> is the timer handle of the timer to free, and should 
originally have been returned by the timer_start function. After a 
timer has been freed it should no longer be referred to. 


€ Return Value 


timer_start returns an integer number representing a 'handle' by which 
a timer will be referred to. 


time_up returns a non-zero (TRUE) or © (FALSE) value depending on 
whether a timer has elapsed or not. 
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timer_total returns an integer value representing the elapsed time 
since a timer was started. 


timer_restart does not return any significant value. 
timer_free does not return any significant value. 

See Also 

delay 

€ Example 

int t; 

t = timer_start(100); // delay for 10 seconds 

while (!time_up(t)) 

timer_free(t); 

// start a timer and loop forever, printing the elapsed time 


// in tenths of seconds 
t = timer_start(0); 


while (1) 
printn(timer_total(t)); 
prints(""); 

} 

TOLOWER 
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% Summary 

tolower (int <chr>); 

% Description 

If the character <chr> is an uppercase character, the tolower function 

returns the lowercase equivalent. Otherwise <chr> is returned un- 

changed. Note that <chr> is an ASCII value, not a string. 

€ Return Value 

An integer value as described above. 


€ See Also 


toupper 
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tone(int <frequency>, int <length>); 
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% Description 


The tone function makes Telix emit a sound of <frequency> for a period 
of time represented by length (in hundredths of a second). 


© Return Value 
None. 
See Also 


alarm 
_sound_on 


€ Example 


tone(659, 14); 


TOUPPER 
2222222299992 
999 999999999999 9999999999999 00 

% Summary 

tolower(int <chr>); 

% Description 

If the character <chr> is an lowercase character, the toupper function 

returns the uppercase equivalent. Otherwise <chr> is returned un- 

changed. Note that <chr> is an ASCII value, not a string. 

€ Return Value 

An integer value as described above. 


€ See Also 


tolower 


TRACK - TRACK_HIT 
222222299999 9222929999999 9999999999999 
9999 9999999999999 9999999999999 

9 Summary 

track(str <trackstr>, int <mode>); 

track_addchr(int <chr>); 

track_free(int <handle>); 


track_hit(int <handle>); 
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% Description 


The track and related functions are used to keep track of and wait for 
certain strings to come in over the comm port, similar in nature to 
the waitfor function. However the latter function can only wait for 
one specific string, while with the track functions can handle more 
strings at the same time (currently up to 16), and they may arrive in 
any order (or not arrive at all). 


The track function tells Telix to keep track of (watch for) the string 
indicated by <trackstr> to come in over the comm port. If <mode> is 0, 
case is significant, if <mode> is 1, case is not significant. The for- 
mer is faster and should be used when the many strings are being 
watched for. Track returns an integer value called a 'track handle' 
which is later used with the track_hit function to check if this 
string came in. 


When track is called, Telix doesn't loop endlessly waiting for the 
string to come in, but instead returns back to the script. As char- 
acters come in, Telix checks to see if any of the strings to be 
tracked have been matched, and marks those that have. A script can at 
any time call the track_hit function to see if the string represented 
by <handle> was received. If track_hit returns a non-zero (TRUE) 
value, then that string was received, otherwise it wasn't. If <handle> 
is 0, then track_hit will return the Lowest numbered handle of any 
strings that came in, or © if none did. The marker on a handle is 
cleared once track_hit has indicated that the appropriate string was 
received. 


while a script is executing, Telix is not in terminal mode, and there- 
fore does not have access to incoming characters, to scan for matching 
strings. Therefore, the terminal function must periodically be called 
to allow Telix to get a look at incoming characters. This function is 
described in the appropriate place in this manual. Alternately, ifa 
script must process these characters itself (with a function like 
cgetc), and therefore can not call the terminal function, they must 
still be passed by the track routines for string matching to work. The 
track_addchr function is used for this. When it is called, Telix 
treats the character represented by <chr> as if it had been received 
from the terminal handler, and uses it to scan for matching strings. 


The track_free function is used to tell Telix to stop tracking a cer- 
tain string. <handle> is a track handle returned by a previous call to 
the track function. It is very important that when a certain string no 
longer needs to be tracked, track_free is called, as tracking a large 
number of strings can slow down Telix execution. If <handle> is 0, 
Telix will stop tracking all strings. 


€ Return Value 


track_addchr and track_free do not return a value. The other functions 
return integer values as described above. 


€ See Also 


waitfor 
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€ Example 


// Log-on to a BBS, answering two prompts in any order. 
// This will wait forever, so for actual use would have 
// to be changed a bit. See sample scripts for examples. 


int stat, t1, t2; 
t1 = track("Name? ", 0); 
t2 = track("Password? ", 0); 


while (1) // loop as long as needed 


terminal(); // call terminal function to allow Telix 
// to look at incoming characters for 
// matches and let Telix process user 
// keystrokes 


stat = track_hit(0); // see if any matches 
if (stat == t1) // name prompt 
cputs("Joe SmithAM"); // send name and continue looping 
if (stat == t2) // password prompt 
cputs("mypassAM"); // send password 
break; // and get out of loop 
} 
} 
track_free(t1); // free track handles 


track_free(t2); 


TRANSTAB 


OCE d d d d d d d dh dh dh: dh: dh: dh: dh: dh: dh dh dh dh da dh d da dh d dh dh: dh: dh: dh: dh: dh dh dh d da A À 
99999 d d d da d da dh dh: dh: dh: dh: dh: d d da d da d da da da da Aa A A 

% Summary 

transtab(str <filename>, int <table>); 

% Description 

The transtab function is used to load or clear the incoming or out- 

going character translation table. <table> stands for the translate 

table to manipulate, with © being the incoming, and 1 being the out- 

going. 


If <filename> is empty (""), Telix will prompt for the name of a 
translate table to load into memory. 


If <filename> is a valid name for a Telix translate table (saved from 
the translate table menu in Telix), it is loaded into memory. 


If <filename> is "*CLEAR*", the current translate table in memory is 
cleared, and Telix will no longer translate incoming characters. 


Return Value 


A value of -1 is returned if there is a problem loading the indicated 
translate table, otherwise a non-zero (TRUE) value is returned. 
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€ Example 


transtab("TELIX.XLT", 0); 


UNLOAD_SCR 
2222222929999 
2222229229999 99992992999 99999999 

% Summary 

unload_scr(str <filename>); 

% Description 

The load_scr function can be used by a script file to load another 

script into memory ahead of time (before it is run). The unload_scr 

function should then be used to unload or take out this script when it 
is no longer needed. <filename> is the name of the script file to un- 

load, and if no extension is given, ".SLC" is assumed. Note that a 

script that is currently executing or that is nested (has called the 

current script) must not be unloaded, since Telix is still executing 
it or will return to it eventually! 

© Return Value 


If there is a problem unloading the script file, a value of -1 is re- 
turned. Otherwise a non-zero (TRUE) value is returned. 


See Also 


load_scr, is_loaded 


€ Example 
int stat; 
stat = load_scr("TEST"); // load TEST.SLC 
ae // do other things 
unload_scr("TEST"); // take TEST.SLC out of memory 


UPDATE_TERM; 
SSSSSSSSSSSSSSSSSSSSSSS SSS 555 MN! 

© Summary 

update_term(); 


% Description 


The update_term function is called to make sure Telix updates certain 
things relating to the video and terminal page. For example, changes 
made to the _back_color and _fore_color system variables will not take 
effect until this function is called. As well Telix may sometimes take 
up to 15 seconds to update the status bar (and in some cases while 
scripts are running, won't update it at all). Calling this function 


ensures that the status bar is updated. 
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© Return Value 
None. 
€ Example 


int temp; // reverse current terminal colors 
temp = back_color; 

back_color fore_color; 

fore_color temp; 

update_term(); 


USAGELOG 
99999999 99999999999 9999999999 9999 9 
999999999999 999999 999999999999 

% Summary 

usage log(str <filename>); 


% Description 


The usagelog function is used to manipulate the Telix usage log fa- 
cility. 

If <filename> is an empty string (""), Telix will ask for the filename 
to open the usage log to, as if the user had pressed Alt-U in terminal 
mode. 


If <filename> contains a valid filename, the usage log is opened to 
that file. The standard usage log is usually called "TELIX.USE". 


If <filename> is "*CLOSE*", and the usage log is currently open, it is 
closed. 


© Return Value 


A value of -1 is returned if there is a problem performing the indi- 
cated operation, otherwise a non-zero (TRUE) value is returned. 


€ See Also 


ustamp, usage_stat 
_usage_fname 


€ Example 


usagelog("TELIX.USE"); 


USAGE_STAT 
99999 99999999999 999999999999 9 9 
9999999999 999999999999 99999999 


€ Summary 


usage_stat(); 
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% Description 
The usage_stat function returns an integer value representing the cur- 
rent status of the Usage Log. If the Usage Log is currently open, a 


non-zero (TRUE) value is returned, otherwise a value of zero (FALSE) 
is returned. 


Return Value 
An integer values as described above. 
€ See Also 


usagelog, capture_stat 


USTAMP 
2229222292299 9292299299299 999999999 
2229222929929 999999999999 999999 

€ Summary 

ustamp(str <text>, int <new_entry>, int <add_n1l>); 


% Description 


The ustamp function is used to place (stamp) text into the Telix usage 
log. If the usage log is currently not open, this function call is 
simply ignored. <text> is the entry that should be placed into the us- 
age log. If <new_entry> contains a non-zero (TRUE) value, the current 
date/time is placed ahead of the text, otherwise it is assumed that 
this is a continuation of a previous entry and no date/time is added. 
If <add_nl> (add new line) is a non-zero (TRUE) value, a Carriage Re- 
turn and Line Feed character are added after the entry. This is usu- 
ally the case unless something else must be added on the same line. 


© Return Value 


A value of -1 is returned if there is a problem writing to the usage 
log, otherwise a non-zero (TRUE) value is returned. 


€ See Also 
usage log 
€ Example 
ustamp("Calling user subroutine... ", 1, 0); 
if (user_sub == - 
ustamp("Failed!, ©, 1); 


else 
ustamp("Successful", 0, 1); 
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VGETCHR 
9999999 9999999999999 99999999 999999999999 
99999 9999999999 9999999999999 9OE 
€ Summary 
vgetchr(); 
% Description 
The vgetchr function is used to read the character (including color 
information) at the current cursor position on the video screen. The 
return value contains the character in the first (low) byte, and the 
color of the character in the higher (second) byte. Each component may 
be extracted using the & and / operators as shown in the example be- 
low. Basically, if 'c' is the returned character/color value, the 
character alone may be obtained by using the expression 
(c & 255) 
while the color value is 
(c / 256) 
€ Return Value 
An integer value as described above. 


€ See Also 


vgetchrs, vgetchrsa, vputchr 


€ Example 

int chr; 

chr = vgetchr(); // Get char/color at current cursor position 
printsc("The character was "); 

printc(chr € 255); // get character by masking out color byte 
printsc(" with a color value of "); 

printn(chr / 256); // shift color byte 


VGETCHRS, VGETCHRSA 
2832232222322422327224223832 72022122225. 

% Summary 

vgetchrs(int <x>, int <y>, str <buf>, int <pos>, int <num>); 

vgetchrsa(int <x>, int <y>, str <buf>, int <pos>, int <num>); 

% Description 

The vgetchrs and vgetchrsa functions are used to read multiple char- 


acters starting from a spot on the screen into a specified variable. 
The first function saves only the characters (a sequence of bytes) 


while the second saves both the characters and color attributes (a se- 
ries of double bytes). <x>,<y> is the spot on the screen to start 
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reading characters. <buf> is the string variable to put characters 
into, starting at an offset of <pos> in the variable. Note that each 
character read in with vgetchrsa will take up two bytes in the string 
variable, since the color attribute is also saved. Note also that 
these functions do not put a © (NULL, or end of string character) at 
the end of the sequence of characters they grab. If the characters re- 
turned by vgetchrs are to be manipulated as a string a © must be added 
at the end with the setchr function. 


Return Value 

None. 

See Also 

vgetchr, vputchrs, vputchrsa 

€ Example 

// copy 20 characters starting from 10,10 on the screen to 20,20 
// Don't keep color attributes 

str buffer[20]; 

vgetchrs(10, 10, buffer, 0, 20); 

vputchrs(20, 20, buffer, 0, 20); 

// copy a 20 by 10 grid of characters with a left hand corner of 


// 10,5 to 40,7, and keep color attributes 
str buffer[400]; // 20 wide * 10 tall * 2 bytes per character 


int y; 

for (y=5; y < 15; y = y+1) // read chars in a loop 
vgetchrsa(10, y, buffer, 2 * 20 * (y - 5), 20); 

for (y= 7; y < 17; y = y+1) // now write them in a loop 


vputchrs(10, y, buffer, 2 * 20 * (y - 7), 20); 


VPUTCHR 
2222222229999 
2222222299999 9292999999999 9999 

€ Summary 

vputchr(int <chr>); 

% Description 

The vputchr function is used to place a character on the screen at the 

current cursor position, specifying color information at the same 

time. <chr> is the character to place on the screen. the low byte con- 
tains the ASCII value of the character, while the second byte contains 
the color value. In general, a if 'c' is the character, and 'color' is 
the color to use, the proper value is obtained with the expression 

(c + color * 256) 
© Return Value 


None. 
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See Also 
vgetchr 
€ Example 


// Place an inverse 'X' in the left top corner of the screen 
gotoxy(0, 0); 
vputchr('X' + 112 * 256); 


VPUTCHRS, VPUTCHRSA 
2292299299999 9992999992999 999 99999999999 
2292299999999 9999 9999999999999 

€ Summary 


vputchrs(int <x>, int <y>, str <buf>, int <pos>, int <num>, int 
<attr>); 


vputchrsa(int <x>, int <y>, str <buf>, int <pos>, int <num>); 
% Description 


The vputchrs and vputchrsa functions are used to write multiple char- 
acters from a spot in a string variable onto the screen at a certain 
position. The first function assumes that the string contains charac- 
ters only, and writes them to the screen using a color attribute of 
<attr>, as described in Appendix C. The second function assumes that 
each character in the string is immediately followed by a color value 
(a series of double bytes). <x>,<y> is the spot on the screen to start 
writing characters. <buf> is the string variable to read characters 
from, starting at an offset of <pos> in the variable. Note that each 
character written with vputchrsa will take up two bytes in the string 
variable, since the color attribute is also there, so the offset 
should reflect this. 


Return Value 

None. 

See Also 

vputchr, vgetchrs, vgetchrsa 
€ Example 


// copy 20 characters starting from 10,10 on the screen to 20,20 
// Don't keep color attributes 

str buffer[20]; 

vgetchrs(10, 10, buffer, 0, 20); 

vputchrs(20, 20, buffer, 0, 20); 


// copy a 20 by 10 grid of characters with a left hand corner of 
// 10,5 to 40,7, and keep color attributes 

str buffer[400]; // 20 wide * 10 tall * 2 bytes per character 
int y; 

for (y=5; y < 15; y = y+1) // read chars in a loop 
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vgetchrsa(10, y, buffer, 2 * 20 * (y - 5), 20); 
for (y= 7; y < 17; y = y+1) // now write them in a loop 
vputchrs(10, y, buffer, 2 * 20 * (y - 7), 20); 


VRSTRAREA 
2222222229999 d 
2222222299999 9992999999999 9999 

% Summary 

vrstrarea(int <vhandle>); 

% Description 

The vrstrarea function is used to restore a previously saved portion 

of the screen. <vhandle> is the video information handle returned by a 


previous call to vsavearea, which saved the screen area. 


Note, it is very important that <vhandle> is a valid handle, returned 
by a previous call to vsavearea, or unpredictable results will happen. 


Return Value 
None. 
€ See Also 


vsavearea 


VSAVEAREA 

1232732733723273273372 2777777220000 2445 
$ Summary 
vsavearea(int <x1>, int <y1>, int <x2>, int <y2>); 


% Description 


The vsavearea function is used to save a rectangular portion of the 
screen (to be later restored). <x1>,<y1> is the upper left corner of 
the area to save, while <x2>,<y2> is the lower right corner. Charac- 
ters (and their colors) currently on the screen in this rectangle are 
saved in a buffer, and a 'handle' is returned, which must be stored 
and used in the subsequent call to vrstrarea to restore the saved 
area. If not enough memory exists to save the video bytes, a value of 
-1 is returned instead. 


Note that Telix has only a limited amount of space for allocating to 
video buffers of this type. At one time, only about as much area as 
would amount to a full screen should be saved with calls to this func- 
tion. 


It is also very important that for every call to this function, there 
is a subsequent call to vrstrarea. If this is not done, memory will 


become used up until no more is left. 
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Return Value 

An integer value representing a 'handle' to the saved area. 
See Also 

vrstrarea 

€ Example 


int vhandle; 
vhandle = vsavearea(®, 0, 79, 24); // save the current screen 


myfunc(); // call a function 

// which modifies screen 
vrstrarea(vhandle); // restore previous screen 
WAITFOR 


9999999 9999999999999 999999999999 99999999 
999999999 9999999999999 999999 00 

€ Summary 
waitfor(str <waitstr>, int <timeout>); 

% Description 
The waitfor function is used to wait for the given string to come in 
over the serial port. Timeout is the maximum amount of time, in sec- 
onds, to wait for the string. Case is not significant, and the string 
must be no longer than 40 characters. 

© Return Value 
A non-zero (TRUE) value is returned if the string is received from the 
serial port in the given time, otherwise a zero (FALSE) value is re- 
turned. 

€ See Also 

track 

€ Example 
if (waitfor("name?", 180)) 

prints("The string 'name?' came in from the comm port."); 


else 


prints("The string 'name?' did not come in from the"); 
prints("comm port in 3 minutes!"); 


} 
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5. SYSTEM VARIABLES 


Telix has quite a large number predefined built-in variables. They are 
called System Variables and are used to store many preferences. There 
are both string and numeric system variables, and they are accessed 
just as you would access any other variable. To help distinguish them 
apart from normal variables, and to avoid confusion, they all start 
with an underscore (_) character. 


The following pages contain descriptions of all the system variables. 
For each variable, a summary and a description are given. An example 
of actual usage of the variable will often be given. 


The variables are listed in alphabetical order. So that you may find 
related variables (and built-in functions), most variable descriptions 
have a 'See also' section, which lists related variables and func- 
tions. 
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ADD_LF 
3322932222322322322232° 2588 Haas a 

€ Summary 

int _add_lf; 

% Description 

If the _add_lf system variable is set to non-zero (TRUE), a Line Feed 


character is automatically added after every Carriage Return character 
that comes in. 


_ALARM_ON 


92999299999 


$ 

$ 

$ 

$ 

$ 

$ 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 


€ Summary 

int _alarm_on; 

% Description 

If the _alarm_on system variable is set to non-zero (TRUE), alarms are 
enabled in Telix. Note that if the _sound_off system variable is set 
to zero (FALSE), alarms will not be heard no matter what the state of 
this variable. 

€ See Also 

alarm 


_sound_on 


_ANSWERBACK_STR 
2222222999999 
2222222299999 9292999999999 9999 

% Summary 

str _answerback_str[19]; 

% Description 

The _answerback_str system variable holds the string which Telix will 

send when a Ctrl-E (ENQ) character is received while in terminal mode. 

If this string is empty, nothing is sent. Note that if Compuserve B 

transfers are enabled, the answerback string will not be sent, since 


CIS B uses the Ctrl-E as part of the transfer process. Maximum Length 
is 19 characters. 


_ASC_RCRTRANS - _ASC_STRIPH 


92999299999 


€ Summary 


f 


asc_rertrans; 


int 
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int _asc_remabort; 

int _asc_rlftrans; 

int _asc_scpacing; 

int _asc_scrtrans; 

int _asc_secho; 

int _asc_sexpand; 

int _asc_slftrans; 

int _asc_slpacing; 

int _asc_spacechr; 

int _asc_striph; 

% Description 

_asc_rertrans determines what Telix does with Carriage Return char- 
acters during ASCII receives. 0 = do nothing; 1 = strip; 2 = add Line 


Feed afterwards. 


_asc_remabort is the character which when received from the remote 
side during an ASCII transfer is a signal to abort the transfer. 


_asc_rlftrans determines what Telix does with Line Feed characters 
during ASCII receives. 0 = do nothing; 1 = strip; 2 = add Carriage Re- 
turn before. 


_asc_scpacing is the time in milliseconds which Telix should wait be- 
fore transmitting each character during ASCII sends. 


_asc_scrtrans determines what Telix does with Carriage Return char- 
acters during ASCII sends. 0 = do nothing; 1 = strip; 2 = add Line 
Feed afterwards. 


If _asc_secho is set to non-zero (TRUE), Telix will echo each char- 
acter during ASCII sends. 


If _asc_sexpand is set to non-zero (TRUE), Telix will expand blank 
lines to a space character, during ASCII sends. 


_asc_slftran determines what Telix does with Line Feed characters dur- 
ing ASCII sends. © = do nothing; 1 = strip; 2 = add Carriage Return 
before. 


_asc_slpacing is the time in tenths of seconds which Telix should wait 
before transmitting each line during ASCII sends. 


_asc_spacechr is the character which Telix should wait for during 
ASCII sends, before transmitting each line (0 means no wait). 


Telix v3.22 - SALT Programming System Variables 100 


If _asc_striph is set to non-zero (TRUE), Telix will strip the high 
(most significant) bit of each character in an ASCII transfer. 


_AUTO_ANS_STR 
9999999 9999999999999 999999999999 99999999 
9999999 9999999999999 99999999 00 

@ Summary 

str _auto_ans_str[48]; 

% Description 

The _auto_ans_str system variable holds the string that should be sent 

to the modem to make it automatically answer the phone when it rings. 

This string is used by the Host Mode script, among others. The string 

will possibly include translation characters as described in the Telix 


manual in the section by that name, and should be sent to the modem 
with the cputs_tr function. Maximum Length is 49 characters. 


€ See Also 


_mdm_init_str 


_BACK_COLOR 
909990900090 


$ 

$ 

$ 

$ 

$ 

$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
oo 


% Summary 

int _back_color; 

% Description 

The _back_color system variable contains the background color which 
should be used for text in terminal mode. Allowable values are from 0 
- 15. Note that changes to this variable may not be reflected until 
the screen is cleared. 


€ See Also 


_fore_color 


_CAPTURE_FNAME 
2292292929999 9999999999999 9999999999 99999 
2292299999999 9999999999999 9999 

€ Summary 


str _capture_fname[64]; 


% Description 


The _capture_fname system variable holds the default capture file 
filename. The maximum length is 64 characters. 
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€ See Also 

capture 

_usage_fname 

_CISB_AUTO 

29299999999 


% Summary 

int _cisb_auto; 

% Description 

The _cisb_auto system variable controls whether Compuserve Quick B 
auto file transfer are allowed. If this variable is set to a © (FALSE) 
value, requests by the remote (Compuserve) to transfer files using the 
Quick B protocol will be ignored. 


See Also 


_zmod_auto 


_CONNECT_STR 

999 9999999999999 9999999999999 
9999999999999 999999 

€ Summary 

str _connect_str[19]; 

% Description 

The _connect_str system variable holds the string which Telix should 

scan for when dialing, and should take to mean that a connection has 

been established. For Hayes type modems it is usually set to 

"CONNECT". Maximum length is 19 characters. 


€ See Also 


_no_connect1 - _no_connect4 


_DATE_FORMAT 
999999 999999999999 9999999999999 999999999 
999999 9999999999999 99999999999 

€ Summary 


int _date_format; 


% Description 


The contents of the _date_format system variable determines what for- 
mat Telix uses for date strings it produces, as follows: 
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0 mm/dd/yy 

1 dd/mm/yy 

2 yy/mm/dd 
€ See Also 
_time_format 
date 
_DEST_BS 
99999 9999999999999 99999999999 
9999999 999999999999 
% Summary 
int _dest_bs; 
% Description 
The _dest_bs system variable controls whether a backspace character 
received by Telix in Terminal Mode erases the character to the left of 
the cursor, or just moves the cursor on top of it on top of it without 
erasing it. If this variable is © (FALSE), Telix will treat the 
backspace as non-destructive, and destructive otherwise. 


€ See Also 


_swap_bs 


_DIAL_PAUSE 
9999999 99999999999 999999999999 99999999 
9999999 9999999999999 A A 
% Summary 
int _dial_pause; 
% Description 
The _dial_pause system variable holds (in seconds) the amount of time 
to wait between the end of one dialing attempt and the beginning of 
another. Most modems don't need more than a 1 second pause. 
_DIAL_TIME 
9999999999999 9999999999999 999999999999 A À 
999999999 9999999999999 999999 00 
€ Summary 
int _dial_time; 


% Description 


The _dial_time system variable holds the amount of time Telix should 
wait for a connection when dialing, in seconds (e.g. 30). 
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See Also 


_dial_pause 


_DIALPOST 
9999999 9999999999999 99999999 d 
2222222299999 9929999999999 
% Summary 
str _dialpost[19]; 
% Description 
The _dialpost system variable holds the string (the dialing postfix) 
which should be sent to the modem after the number, when dialing. For 
Hayes type modems, it is usually just a Carriage Return. Maximum 
length is 19 characters. This string will possibly include some trans- 
lation characters, as described in the Telix manual, and should be 
sent to the modem with the cputs_tr function. 


€ See Also 


_dialpref, _dialpref2, _dialpref3, _redial_stop 


_DIALPREF 
OCE d d d d da da dh dh dh dh: dh: dh: dh: dh: dh dh dh dh dh dh dh dh da dh d dh d 
9999999 d d d da dh: dh: dh: d: dh: dh: d d da da da. d da da da da da A A 
€ Summary 
str _dialpref[19]; 
str _dialpref2[19]; 
str _dialpref3[19]; 
% Description 
The _dialpref system variable holds the string which should be sent to 
the modem before the number, when dialing. For Hayes type modems, it 
is usually set to "ATDT". Maximum length is 19 characters. This string 
will possibly include translation characters, as described in the 


Telix manual, and should be sent to the modem with the cputs_tr func- 
tion. 


The _dialpref2 and _dialpref3 variables are the other two dialing pre- 
fixes that may be defined in Telix. 


See Also 


_dialpost, _redial_stop 
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_DIR_PROG 
9999999 9999999999999 999999999999 99999999 
999 999999999999 9999999999999 9OO 

€ Summary 

str _dir_prog[15]; 

% Description 

The _dir_prog system variable holds the name of the disk directory 

program that should be run when the user selects the 'Files directory' 


option of the DOS Functions menu. If this variable is left empty (""), 
the DOS 'dir' command is used. Maximum length is 15 characters. 


_DISP_FREE 
9999999 9999999999999 999999999999 d 
99 999 9999999999999 999999 
€ Summary 
int _disp_free 
% Description 
If the _disp_free system variable is set to non-zero (TRUE), Telix 
will display the amount of free space available on the drive when the 
user presses ALt-R to download a file. 
_DOWN_DIR 
9999999 9999999999999 999999999999 d 
999 999999999999 9999999999999 00 
€ Summary 
str _down_dir[64]; 
% Description 
The _down_dir system variable holds the default download directory 
name. When a file is downloaded (received), if the user specifies a 
drive and/or directory in the name, the file is put there. However, if 
only a name is specified, the file is placed in the directory in- 
dicated by _down_dir. The maximum length is 64 characters, and this 
string should end with the backslash character, '\'. 


€ See Also 


_up_dir, receive 


_EDITOR 


99999 99999999999 999999999999 999999999999 


2299229999999 9999 9999999999999 
% Summary 


str _editor[64]; 
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% Description 


The _editor system variable holds the name of the editor that should 
be run when the user presses Alt-A. The editor should either be on the 
DOS Path, in which case only the name needs to be given, or else the 
entire pathname (drive, directory, name) must be given. The maximum 
length is 64 characters. If a batch file is to be run the .BAT exten- 
sion must be given. 


_ENTRY_ENUM 


9299999999 
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$ 

$ 
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$ 
$ 
$ 
$ 
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$ 
$ 
$ 
$ 
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oo 
oe 
oo 


% Summary 

int _entry_enum; 

% Description 

The _entry_enum variable is set by the dialing routines. When a con- 
nection is established while dialing, the entry number of the dialing 
directory entry connected to is stored here. If a manual number is 
connected to, the value © is stored here. 

€ See Also 

_entry_name 


dial, redial 


_ENTRY_NAME - _ENTRY_PASS 
OCE d d d d d da d dh: dh: dh: dh: dh: dh: dh: dh dh dh dh dh dh dh dh dh dh dh d 
99 d d d d d d d d da dh: dh: dh: dh: dh: dh: dh dh da d da da da da da da d A A 
% Summary 
str _entry_name[29]; 
str _entry_num[17]; 
str _entry_pass[14]; 
% Description 
The _entry_name system variable is set by the dialing routines. When a 
connection has been established the name portion of the dialing direc- 
tory entry connected to is copied here, for use by script files. The 
maximum Length is 29 characters. 
The _entry_num system variable is set in the same way, and holds the 
phone number of the entry connected to. The maximum length is 17 char- 
acters. 
The entry_pass system variable is set in the same way, and holds the 


password from the entry connected to. This may be used to perform lo- 
gons. The maximum length is 14 characters. 
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See Also 


_entry_enum 
dial, redial 


_EXT_FILESPEC; 
9999999 9999999999999 999999999999 99999999 
99999 9999999999 9999999999999 OE 

€ Summary 

str _ext_filespec[64]; 

% Description 


This variable is for use by scripts implementing external protocols. 
When an external protocol has been defined as called by a script, this 
variable is first loaded with the filespec (file specification) typed 
by the user at the transfer menu. The appropriate script is then run. 
The script can for example pass this name to a program which imple- 
ments the actual protocol. Note that some file transfer protocols do 
not require the user to supply the name on downloads, in which case 
this variable is left empty. 


_FORE_COLOR 
909990900090 


$ 

$ 

$ 

$ 

$ 

$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
oo 


€ Summary 

int _fore_color; 

% Description 

The _fore_color system variable contains the foreground color which 
should be used for text in terminal mode. Allowable values are from 0 
- 15. Note that changes to this variable may not be reflected until 
the screen is cleared. 


See Also 


_back_color 


_IMAGE_FILE; 
2222292292999 9999299999999 9999 99999999999 
2292229999999 9999 9999999999999 

€ Summary 


str _image_file[64]; 


% Description 


The _image_file system variable holds the full name of the file that 
screen images are saved to when the user presses Alt-I while in ter- 
minal mode. If this file already exists, data is appended to it. 
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_LOCAL_ECHO 
2232232222322322322232°288 Haan a 

€ Summary 

int _local_echo; 

% Description 

The _local_echo system variable controls whether or not characters 


typed in terminal mode are echoed on the screen. If _local_echo is set 
to non-zero (TRUE), characters are echoed, otherwise they are not. 


_MDM_HANG_STR 
99 9999999999999 999999999999 9999999999999 
99999 999999999999 9999999999999 

9 Summary 

str _mdm_hang_str[19]; 

9 Description 


The _mdm_hang_str system variable holds the string that should be sent 
to the modem to hang it up when the user presses Alt-H. Note that this 
string will only be sent to the modem if Telix can't first hang-up the 
modem by turning off a signal on the serial port called the DTR line. 
This string may contain translation characters as defined in the Telix 
manual, and should be sent to the modem with the cputs_tr function. 
Maximum length is 19 characters. 


€ See Also 


_mdm_init_str, _auto_ans_str 


_MDM_INIT_STR 
99999999909 


$ 

$ 

$ 

$ 

$ 

$ 
od 
oe 
oe 
oe 
od 
oe 
oe 
oe 
od 
oe 
oe 
oe 
od 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 


€ Summary 

str _mdm_init_str[49]; 

% Description 

The _mdm_init system variable holds the string that should be sent to 
the modem when Telix starts-up. It is usually used to make sure cer- 
tain settings in the modem are right. This string may contain transla- 


tion characters as defined in the Telix manual, and should be sent to 
the modem with the cputs_tr function. Maximum length is 49 characters. 


See Also 


_auto_ans_str, _mdm_hang_str 
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_NO_CONNECT1 - _NO_CONNECT4 
9999999 9999999999999 99999999 999999999999 
999 999999999999 9999999999999 A A 
€ Summary 
str _no_connect1[19]; 
str _no_connect2[19]; 
str _no_connect3[19]; 
str _no_connect4[19]; 
% Description 
These system variables contain the strings that Telix should scan for 
when dialing, and take to mean that a connection has not been estab- 
lished (i.e., the number was busy or there was no answer). The maximum 
Length for each string is 19 characters. 


€ See Also 


_connect_str 


_QDBAR_ON 
SSSSSSSSSSSSSSSSSSSSSSS SSS 535 MIN! 

$ Summary 

int _qdbar_on; 

® Description 

If the _qdbar_on system variable is set to non-zero (TRUE), the quick 


dialing bar is shown first when Alt-D is pressed; otherwise the user 
is taken directly to the dialing directory screen. 


_REDIAL_STOP 
99999999999 dh: dh: dh: dh: dh dh dh dh dh dh dh dh dh 9999999999999 d d À 
999 d d d d d da da da dh: dh: dh: dh: dh: dh: d da da d d d da da da da da A A 

% Summary 

str _redial_stop[19]; 

% Description 

The _redial_stop system variable holds the string that should be sent 

to the modem to stop a dialing attempt. It usually just holds a Car- 

riage Return character. This string may contain translation characters 


as described in the Telix manual, and should be sent to the modem with 
the cputs_tr function. Maximum length is 19 characters. 


See Also 


_dialpref, _dialpref2, _dialpref3, _dialpost 
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_SCR_CHK_KEY 
ERRE III IT 333333333535 IN! 

$ Summary 

int _scr_chk_key; 

® Description 


Between every command while executing a script file, Telix checks the 
keyboard buffer to see if the user has requested an abort. This how- 
ever gets in the way of the inkey function among others. As well, it 
is sometimes necessary to stop the user from being able to abort the 
script. If _scr_chk_key is set to zero (FALSE), Telix will no longer 
check for user aborts requests during script execution. Setting it 
back to non-zero (TRUE) will turn the checks back on. When modifying 
this variable in a script file, it is a good idea to save the old 
state in a scratch variable and restore it when done. 


€ See Also 


inkey 


_SCRIPT_DIR 
9099990000090 


$ 

$ 

$ 

$ 

$ 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 


€ Summary 

str _script_dir[64]; 

% Description 

The _script_dir system variable holds the full path of the directory 
where Telix should look for compiled script files when a script is se- 
lected to be run. When a script is selected to be run, Telix uses this 
procedure: if the name includes the drive and/or directory, only that 
path is searched. If the name includes only the filename, the current 
directory is first searched for the script file, and then the direc- 
tory pointed to by the _script_dir variable. This string should end in 
the slash character, '\'. The maximum allowed length is 64 characters. 
€ See Also 


_telix_dir, _up_ dir, _down_dir 

_SOUND_ON 
9999999999999 999999999999 999999999 999999 
909 9999999999999 999999999 

% Summary 


int _sound_on; 
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% Description 


If the _sound_on system variable is set to non-zero (TRUE) sound is 
enabled in Telix, otherwise all sound is shut off. 


€ See Also 


_alarm_on 


_STRIP_HIGH 
9099900900090 


$ 
$ 

$ 

$ 

$ 

$ 

$ 

$ 
$ 
$ 
$99 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
oo 
oo 
oe 
oo 


% Summary 

int _strip_high; 

% Description 

The _strip_high system variable controls what Telix does with the high 
(most significant) bit of incoming characters while in terminal mode. 


If this variable is set to s non-zero (TRUE) value, Telix will strip 
the high bit of incoming characters. 


_SWAP_BS 
9999999999 


oo 
oe 

$ 

$ 

$ 

$ 

$ 

$ 
$ 
$ 
$9 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
oo 


€ Summary 

int _swap_bs; 

% Description 

The _swap_bs system variable controls what Telix sends when the 
Backspace key is pressed. If this variable is 0, Telix will send a 
Backspace character when Backspace is pressed, and a DEL character 
when Ctrl-Backspace is pressed. If this variable is set to 1, Telix 
will reverse these codes. 


€ See Also 


_dest_bs 


_TELIX_DIR; 
sssesseesesssssseesssssssseessee eee eeees 

$ Summary 

str _telix_dir[64]; 


% Description 


The _telix_dir system variable holds the full path to reach the Telix 
program's base directory (e.g. 'C:\TELIX\'). Changing this variable is 
not recommended, as if a wrong value is used, Telix will probably not 
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be able to find many needed files. The maximum length is 64 charac- 
ters. 


If this variable is changed, it is imperative that a backslash char- 
acter, '\', is found at the end. Telix builds paths to many files by 
appending certain names to this string. If the slash is missing, it 
will cause many problens. 

€ See Also 


_script_dir, _up_dir, _down_dir 


_TIME_FORMAT 


9299999999 


oo 
oe 
oo 

$ 

$ 

$ 

$ 

$ 
$ 
$ 
$ 
$ 
ZE 
KA 
KA 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
oo 


€ Summary 

int _time_format; 

% Description 

The _time_format system variable determines what format Telix uses for 
time strings it produces. If _time_format is 0, Telix will use a 12 
hour format, otherwise a 24 hour format will be used. 

€ See Also 

_date_format 


time 


_UP_DIR 
9999999 9999999999999 999999999999 999999 9O9 
999 999999999999 9999999999999 A A 
€ Summary 
str _up_dir[64]; 
% Description 
The _up_dir system variable holds the default upload directory name. 
When a file is to be ed (sent), if the user specifies a drive and/or 
directory in the name, the file is taken from there. However, if only 
a name is specified, the file is searched for in the directory in- 
dicated by _up_dir. This variable should end with a slash character, 
IN", The maximum length is 64 characters. 


€ See Also 


_down_dir 
send 
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_USAGE_FNAME 
2222932222322322322232°2588 Haas la 

€ Summary 

str _usage_fname[64]; 

% Description 


The _usage_fname system variable holds the default Usage Log filename. 
The maximum length is 64 characters. 


€ See Also 
_capture_fname 
usagelog 
_ZMOD_AUTO 


9299999999 


oe 
oe 
oe 
$ 

$ 

$ 

$ 

$ 

oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 
oe 


% Summary 

int _zmod_auto; 

% Description 

The _zmod_auto system variable controls whether or not Zmodem auto- 
downloads are allowed. If Telix is in terminal mode and receives an 
auto download request Telix will ignore it if this variable is set to 
a © (FALSE) value (however, the user can still receive the file by 
manually selecting the Zmodem protocol from the Alt-R menu). 


€ See Also 


_cisb_auto 


_ZMOD_RCRASH 
2222222299999 
2222222229999 9299299299999 999999 

€ Summary 

int _zmod_rcrash; 

% Description 

The _zmod_rcrash system variable controls whether the Zmodem receive 

Crash Recovery (resume) option is on. If this variable is set toa 

non-zero (TRUE) value, Telix will try to resume aborted transfers dur- 


ing a Zmodem download. 


See Also 


_zmod_scrash 
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_ZMOD_SCRASH 
2222222999992 
2222229292999 9929929999999 999999 

€ Summary 

int _zmod_scrash; 

% Description 

The _zmod_scrash system variable controls whether the Zmodem send 

Crash Recovery (resume) option is on. If this variable is set toa 

non-zero (TRUE) value, Telix will try to tell the other side to resume 

aborted transfers during a Zmodem upload. 


€ See Also 


_zmod_rcrash 
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6. APPENDIX A - ASCII CHARACTER SET 


The ASCII character set consists if 128 characters, with each char- 
acter having an ASCII value, in the range of © to 127. The IBM PC uses 
the IBM Extended ASCII set, which adds a further 128 values, to pro- 
vide extra symbols. The following table lists the regular ASCII char- 
acter set. The first column contains the ASCII control characters, 
which can not normally be printed, and are given by name. 


Dec Hex Ctrl Name Dec Hex Chr Dec Hex Chr Dec Hex Chr 
© 00 A@ NUL 32 20 64 40 @ 96 60 ` 
01 AA SOH 33 21 ! 65 41 A 97 61 a 
2 02 AB STX 34 22 " 66 42 B 98 62 b 
3 03 ^C ETX 35 23 # 67 43 C 99 63 c 
4 04 AD EOT 36 24 $ 68 44 D 100 64 d 
5 05 ^E ENQ 37 25 % 69 45 E 101 65 e 
6 06 AF ACK 38 26 & 70 46 F 102 66 f 
7 07 AG BEL 39 27 ' 71 47 G 103 67 g 
8 08 AH BS 40 28 ( 72 48 H 104 68 h 
9 09 AI HT 41 29 ) 73 49 I 105 69 i 
10 Oa AJ LF 42 2a * 74 4a J 106 6a j 
11 Ob AK VT 43 2b + 75 4b K 107 6b k 
12 Oc AL FF 44 2c , 76 4c L 108 6c 1 
13 Od AM CR 45 2d - 77 4d M 109 6d m 
14 Oe AN SO 46 2e . 78 4e N 110 6e n 
15 ef ^0 SI 47 2f / 79 Af 0 111 6f o 
16 10 ^P DLE 48 30 0 80 50 P 112 70 p 
17 11 ^Q DC1 49 31 1 81 51 Q 113 71 q 
18 12 AR DC2 50 32 2 82 52 R 114 72 r 
19 13 AS DC3 51 33 3 83 53 S 115 73 s 
20 14 ^T DC4 52 34 4 84 54 T 116 74 t 
21 15 ^U NAK 53 35 5 85 55 U 117 75 u 
22 16 ^V SYN 54 36 6 86 56 V 118 76 v 
23 17 ^W ETB 55 37 7 87 57 W 119 77 w 
24 18 AX CAN 56 38 8 88 58 X 120 78 x 
25 19 AY EM 57 39 9 89 59 Y 121 79 y 
26 la AZ SUB 58 Za : 90 5a Z 122 7a Z 
27 1b ^[ ESC 59 3b ; 91 5b [ 123 7b { 
28 1c ^A FS 60 3c < 92 5c \ 124 7c | 
29 1d A] GS 61 3d = 93 5d ] 125 7d } 
30 le AA RS 62 3e > 94 5e A 126 7e ~ 
31 ıf A_ US 63 3f ? 95 5f 127 7f DEL 
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7. APPENDIX B - EXTENDED KEY SCAN CODES 


The following chart lists keyboard scan codes for special non-ASCII 
keys, as returned by inkey and inkeyw, and used by the keyget, keyset, 
keyload, and keysave SALT functions. Normal keys which are within the 
ASCII set are listed in the preceding appendix. 


Key Normal w / Ctrl W / Alt w / Shift 
Dec Hex Dec Hex Dec Hex Dec Hex 
F1 15104 3b00 24064 5e00 26624 6800 21504 5400 
F2 15360 3c00 24320 5f00 26880 6900 21760 5500 
F3 15616 3d00 24576 6000 27136 6a00 22016 5600 
F4 15872 3e00 24832 6100 27392 6b00 22272 5700 
F5 16128 3f00 25088 6200 27648 6c00 22528 5800 
F6 16384 4000 25344 6300 27904 6d00 22784 5900 
F7 16640 4100 25600 6400 28160 6e00 23040 5a00 
F8 16896 4200 25856 6500 28416 6f00 23296 5b00 
F9 17152 4300 26112 6600 28672 7000 23552 5c00 


Left 19200 4b00 29440 7300 
Right 19712 4d00 29696 7400 
Home 18176 4700 30464 7700 
End 20224 4f00 29952 7500 
PgUp 18688 4900 33792 8400 
PgDn 20736 5100 30208 7600 
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8. APPENDIX 


Several SALT functions, 


C - COLOR VALUES 


such as pstra, 


Appendix C 


use color attribute values. 


116 


A 


character on the text screen has a foreground color, and a background 


color. Possible colors are numbered as follows: 


Black 

Blue 

Green 

Cyan 

Red 

Magenta 
Brown 

Light Grey 
Dark Grey 
Light Blue 
Light Green 
Light Cyan 
Light Red 
Light Magenta 
Yellow 
White 


To obtain a color attribute value for a color combination, the formula 


1S 


color attribute value = 


foreground color value + (16 * background color value) 


Therefore, a Yellow character on a Blue background would have a color 


attribute value of 30 (14 + (16 * 1)). 
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